atom-agent 0.3.0

package/dist/snapshots.js

@@ -0,0 +1,243 @@
+// File snapshots for /rewind (ticket 01).
+//
+// Every write/edit auto-snapshots the affected file's prior bytes BEFORE the
+// mutation runs (the capture calls live inside writeTool/editTool, so every
+// caller — loop, tests, future subagents — is covered regardless of path).
+// Snapshots are silent: no prompt, no config, and a snapshot failure never
+// fails the mutation it precedes (capturePriorBytes resolves null).
+//
+// Session-scoped and in-memory (small files stay as Buffers; files over
+// SNAPSHOT_OVERFLOW_BYTES spill a copy under the OS temp dir — never the
+// repo itself). Restores are byte-exact and hash-verified (sha256 of the
+// bytes on disk must equal the pre-mutation hash, not a model rewrite).
+// Shell side effects (bash) are explicitly out of scope: commands are never
+// snapshotted and cannot be undone — the /rewind UI says so outright.
+import { createHash, randomBytes } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+// Large-file spill threshold + session cap (oldest checkpoints drop off;
+// their temp copies are removed best-effort so the session cannot leak).
+export const SNAPSHOT_OVERFLOW_BYTES = 256 * 1024;
+export const MAX_CHECKPOINTS = 50;
+const SNAPSHOT_DIR = "atom-snapshots";
+let checkpoints = [];
+let seq = 0;
+// Probe for the live conversation lengths (registered once by App on mount;
+// tools.ts must stay free of App/zen imports, so the lengths flow in here).
+// Null when unregistered (plain tool tests) — marks default to 0.
+let historyProbe = null;
+export function registerHistoryProbe(fn) {
+    historyProbe = fn;
+}
+function currentMarks() {
+    try {
+        const m = historyProbe?.();
+        if (m !== null &&
+            m !== undefined &&
+            typeof m.history === "number" &&
+            Number.isFinite(m.history) &&
+            typeof m.turns === "number" &&
+            Number.isFinite(m.turns)) {
+            return { history: Math.max(0, Math.floor(m.history)), turns: Math.max(0, Math.floor(m.turns)) };
+        }
+    }
+    catch {
+        // A broken probe must never break the mutation being snapshotted.
+    }
+    return { history: 0, turns: 0 };
+}
+/** Test isolation (plus any future session reset): drops every checkpoint. */
+export function clearSnapshots() {
+    for (const cp of checkpoints) {
+        for (const f of cp.files) {
+            if (f.overflowPath) {
+                void fsp.rm(f.overflowPath, { force: true }).catch(() => undefined);
+            }
+        }
+    }
+    checkpoints = [];
+    seq = 0;
+}
+/** Newest-last copy for the picker and tests (the stored entries stay private). */
+export function listCheckpoints() {
+    return [...checkpoints];
+}
+export function getCheckpoint(id) {
+    return checkpoints.find((c) => c.id === id);
+}
+function snapshotDir() {
+    return path.join(os.tmpdir(), SNAPSHOT_DIR);
+}
+function newCheckpointId(nextSeq) {
+    return `${Date.now().toString(36)}-${nextSeq.toString(36)}${randomBytes(3).toString("hex")}`;
+}
+async function readPrior(abs) {
+    let bytes = null;
+    try {
+        bytes = await fsp.readFile(abs);
+    }
+    catch {
+        return { abs, existed: false, hash: null, bytes: null, overflowPath: null };
+    }
+    const hash = createHash("sha256").update(bytes).digest("hex");
+    if (bytes.byteLength > SNAPSHOT_OVERFLOW_BYTES) {
+        try {
+            const dir = snapshotDir();
+            await fsp.mkdir(dir, { recursive: true });
+            const name = `snapshot-${process.pid}-${Date.now().toString(36)}-${randomBytes(4).toString("hex")}.bin`;
+            const file = path.join(dir, name);
+            await fsp.writeFile(file, bytes);
+            return { abs, existed: true, hash, bytes: null, overflowPath: file };
+        }
+        catch {
+            // Spill failed — keep the in-memory bytes (restore still works).
+        }
+    }
+    return { abs, existed: true, hash, bytes, overflowPath: null };
+}
+function pushCheckpoint(label, files, marks) {
+    seq += 1;
+    const cp = {
+        id: newCheckpointId(seq),
+        seq,
+        at: Date.now(),
+        label,
+        historyLength: marks.history,
+        turnsLength: marks.turns,
+        files,
+    };
+    checkpoints.push(cp);
+    while (checkpoints.length > MAX_CHECKPOINTS) {
+        const dropped = checkpoints.shift();
+        for (const f of dropped?.files ?? []) {
+            if (f.overflowPath) {
+                void fsp.rm(f.overflowPath, { force: true }).catch(() => undefined);
+            }
+        }
+    }
+    return cp;
+}
+// THE capture hook: snapshot prior bytes, then record one checkpoint. Never
+// throws and never returns an error into the mutation path — a missed
+// snapshot just means no checkpoint for this write.
+export async function capturePriorBytes(abs, label) {
+    try {
+        if (typeof abs !== "string" || abs.length === 0)
+            return null;
+        const file = await readPrior(abs);
+        const cleanLabel = typeof label === "string" && label.length > 0 ? label : "edit";
+        return pushCheckpoint(cleanLabel, [file], currentMarks());
+    }
+    catch {
+        return null;
+    }
+}
+async function priorBytesOf(f) {
+    if (!f.existed)
+        return null;
+    if (f.bytes !== null)
+        return f.bytes;
+    if (f.overflowPath) {
+        try {
+            return await fsp.readFile(f.overflowPath);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+// Restore every file in the checkpoint to its prior bytes (or delete files
+// the mutation created), hash-verified. Returns a one-line summary or an
+// "Error: ..." string — never throws. onRestored lets the caller refresh
+// derived state per file (tools.ts stale-read fingerprints); text is null
+// for deletions. Observer errors never break the restore.
+export async function restoreCheckpointFiles(id, onRestored) {
+    const cp = getCheckpoint(id);
+    if (!cp)
+        return "Error: unknown checkpoint";
+    let restored = 0;
+    for (const f of cp.files) {
+        try {
+            if (!f.existed) {
+                try {
+                    await fsp.rm(f.abs, { force: true });
+                }
+                catch {
+                    return `Error: rewind failed: cannot remove ${f.abs}`;
+                }
+                try {
+                    onRestored?.(f.abs, null);
+                }
+                catch {
+                    // ignore observer errors
+                }
+                restored += 1;
+                continue;
+            }
+            const prior = await priorBytesOf(f);
+            if (prior === null)
+                return `Error: rewind failed: snapshot for ${f.abs} is unreadable`;
+            try {
+                await fsp.mkdir(path.dirname(f.abs), { recursive: true });
+                await fsp.writeFile(f.abs, prior);
+            }
+            catch {
+                return `Error: rewind failed: cannot restore ${f.abs}`;
+            }
+            let check;
+            try {
+                check = await fsp.readFile(f.abs);
+            }
+            catch {
+                return `Error: rewind failed: cannot verify ${f.abs}`;
+            }
+            if (createHash("sha256").update(check).digest("hex") !== f.hash) {
+                return `Error: rewind failed: hash mismatch restoring ${f.abs}`;
+            }
+            try {
+                onRestored?.(f.abs, prior.toString("utf8"));
+            }
+            catch {
+                // ignore observer errors
+            }
+            restored += 1;
+        }
+        catch {
+            return `Error: rewind failed: cannot restore ${f.abs}`;
+        }
+    }
+    if (restored === 0)
+        return `(checkpoint #${cp.seq} — nothing to restore)`;
+    return `(rewound ${restored} file(s) to checkpoint #${cp.seq})`;
+}
+// Conversation-rewind cut for a checkpoint mark: drop the whole turn that
+// contains the mark (submit's splice(rollbackTo) rollback semantics), so
+// assistant/tool pairing can never split. A mark taken after a turn already
+// committed (an assistant message without tool_calls sits inside the slice)
+// keeps everything through the mark — only later turns drop. keepFirst is
+// the floor (1 keeps the system prompt for API history; 0 for the display
+// transcript, which has no system line). Pure — unit-tested directly.
+export function conversationCutIndex(messages, mark, keepFirst = 1) {
+    const len = messages.length;
+    const floor = Math.max(0, Math.floor(keepFirst));
+    if (len <= floor)
+        return len;
+    const m = Math.max(floor, Math.min(Number.isFinite(mark) ? Math.floor(mark) : len, len));
+    let turnStart = -1;
+    for (let i = m - 1; i >= floor; i--) {
+        if (messages[i]?.role === "user") {
+            turnStart = i;
+            break;
+        }
+    }
+    if (turnStart === -1)
+        return floor;
+    for (let i = turnStart; i < m; i++) {
+        const msg = messages[i];
+        if (msg !== undefined && msg.role === "assistant" && msg.hasToolCalls !== true)
+            return m;
+    }
+    return turnStart;
+}

package/dist/system.js

@@ -0,0 +1,22 @@
+// Base system prompt for the Atom chatbot (owner-editable).
+//
+// System-prompt layering (two layers, appended at startup):
+//   final system = <lines below joined> + "\n\n" + <repo AGENTS.md>
+// (see buildSystemPrompt in zen.ts; the AGENTS.md overlay is capped at
+// 12KB). To change the bot's base identity, edit the lines below; to
+// add project/repo instructions, edit AGENTS.md.
+//
+// NOTE: the first line is pinned — tests/app.test.tsx asserts the prompt
+// starts with it. Keep it stable.
+export const SYSTEM_PROMPT = [
+    "You are ATOM, a long-horizon coding agent that works through tools.",
+    "",
+    "Loop every task: explore, plan, implement, verify, report.",
+    "Plan 3+ step tasks with todowrite: full list up front, exactly one in_progress, mark completed immediately, never batch.",
+    "Read files before editing them. Search existing code before writing new code. Match surrounding patterns.",
+    "Prefer the smallest correct change. Fix root causes. Handle errors and edge cases. Remove dead code.",
+    "Ground every claim in tool output, never in memory. Run commands to check facts.",
+    "After each tool result, reflect briefly, then take the best next action toward the goal.",
+    "Keep calling tools until verified done. Never end on an unverified summary or a guess.",
+    "Done means tests and typecheck pass, or the blocker is named with its evidence.",
+].join("\n");