atom-agent 1.3.0 → 1.5.0

package/dist/todos.js

@@ -0,0 +1,241 @@
+// Per-session todos (ticket 05): a task checklist scoped to each session
+// that persists across compactions and restarts, so the agent's plan and
+// progress are never lost when old chat text is summarized away.
+//
+// Storage: namespaced under the multi-session record's generic
+// `metadata.todos` key (src/sessions.ts) via the existing
+// updateSession/getSession APIs — no schema edits, no new files on disk.
+// Todos live OUTSIDE compacted chat text, so compaction (summary+tail)
+// can never summarize them away; the summary only carries a context
+// backstop (see formatGoalForCompact), never the record of truth.
+//
+// Status vocabulary is exactly src/tools/todo.ts's
+// ("pending" | "in_progress" | "completed") — matched, not reinvented.
+// Runtime invariants (at most one in_progress, completed-stays-completed,
+// all-completed clears) stay owned by the tools/todo.ts layer; this module
+// validates SHAPE only, so a saved record always replays through
+// todowriteTool cleanly.
+//
+// Totality (mirroring goal.ts): serialize/restore never throw. Old records
+// without the todos key read as an empty list; a malformed todos value
+// degrades to empty WITHOUT failing the session load (same posture as the
+// goal field). The pure CRUD ops below throw Error on invalid input —
+// those are programmer errors with explicit messages, never silent.
+//
+// Import budget: type-only import from ./tools/todo.js (erased at compile,
+// zero runtime coupling) plus no value imports — this module never touches
+// App, sessions, compact, config, or the tool registry.
+// Namespace inside Session.metadata. Never read or write metadata.filediffs
+// (ticket 06 owns it).
+export const TODOS_METADATA_KEY = "todos";
+const TODO_STATUSES = [
+    "pending",
+    "in_progress",
+    "completed",
+];
+const TODO_PRIORITIES = ["high", "medium", "low"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Shape check mirroring todowriteTool's item validation (same vocabulary,
+// same strictness): non-empty content, known status, known priority when
+// present, string activeForm when present. Unknown extra keys are ignored.
+// Returns a clean deep copy, or null when invalid.
+export function validateTodoRecord(value) {
+    try {
+        if (!isRecord(value))
+            return null;
+        if (typeof value["content"] !== "string" || value["content"].length === 0) {
+            return null;
+        }
+        const status = value["status"];
+        if (status !== "pending" &&
+            status !== "in_progress" &&
+            status !== "completed") {
+            return null;
+        }
+        const clean = {
+            content: value["content"],
+            status,
+        };
+        if (value["priority"] !== undefined) {
+            const priority = value["priority"];
+            if (priority !== "high" && priority !== "medium" && priority !== "low") {
+                return null;
+            }
+            clean.priority = priority;
+        }
+        if (value["activeForm"] !== undefined) {
+            if (typeof value["activeForm"] !== "string")
+                return null;
+            if (value["activeForm"].length > 0)
+                clean.activeForm = value["activeForm"];
+        }
+        return clean;
+    }
+    catch {
+        return null;
+    }
+}
+function cleanTodoList(list) {
+    return list.map((t) => ({ ...t }));
+}
+function checkedIndex(length, index, verb) {
+    if (typeof index !== "number" ||
+        !Number.isFinite(index) ||
+        Math.floor(index) !== index) {
+        throw new Error(`${verb}: index must be an integer (got ${String(index)})`);
+    }
+    if (index < 1 || index > length) {
+        throw new Error(`${verb}: index ${index} out of range (list has ${length} item(s))`);
+    }
+    return index - 1;
+}
+// Append one item (1-based position = end). Throws Error on a malformed item.
+export function createTodo(list, item) {
+    const clean = validateTodoRecord(item);
+    if (!clean) {
+        throw new Error(`createTodo: item must be {content: non-empty string, status: "pending" | "in_progress" | "completed", priority?: "high" | "medium" | "low", activeForm?: string}`);
+    }
+    return [...cleanTodoList(list), clean];
+}
+// Patch ONE item by 1-based index (status transitions flow through here —
+// completeTodo below is the named common case). Unknown patch keys are
+// ignored; an empty patch is a no-op copy. Throws Error on a bad index or
+// an invalid patched value.
+export function updateTodo(list, index, patch) {
+    const at = checkedIndex(list.length, index, "updateTodo");
+    const p = isRecord(patch) ? { ...patch } : {};
+    const next = { ...list[at] };
+    if (p["status"] !== undefined) {
+        const status = p["status"];
+        if (status !== "pending" &&
+            status !== "in_progress" &&
+            status !== "completed") {
+            throw new Error(`updateTodo: status must be one of "pending", "in_progress", "completed" (got ${JSON.stringify(status) ?? String(status)})`);
+        }
+        next.status = status;
+    }
+    if (p["content"] !== undefined) {
+        if (typeof p["content"] !== "string" || p["content"].length === 0) {
+            throw new Error(`updateTodo: content must be a non-empty string`);
+        }
+        next.content = p["content"];
+    }
+    if (p["priority"] !== undefined) {
+        const priority = p["priority"];
+        if (priority !== "high" && priority !== "medium" && priority !== "low") {
+            throw new Error(`updateTodo: priority must be one of "high", "medium", "low" (got ${JSON.stringify(priority) ?? String(priority)})`);
+        }
+        next.priority = priority;
+    }
+    if (p["activeForm"] !== undefined) {
+        if (typeof p["activeForm"] !== "string") {
+            throw new Error(`updateTodo: activeForm must be a string`);
+        }
+        if (p["activeForm"].length > 0) {
+            next.activeForm = p["activeForm"];
+        }
+        else {
+            delete next.activeForm;
+        }
+    }
+    const out = cleanTodoList(list);
+    out[at] = next;
+    return out;
+}
+// Mark one item completed by 1-based index. Throws Error on a bad index.
+export function completeTodo(list, index) {
+    return updateTodo(list, index, { status: "completed" });
+}
+// Move the item at 1-based `from` to 1-based `to` (order = array order).
+// Throws Error on a bad index.
+export function reorderTodo(list, from, to) {
+    const fromAt = checkedIndex(list.length, from, "reorderTodo");
+    const toAt = checkedIndex(list.length, to, "reorderTodo");
+    if (fromAt === toAt)
+        return cleanTodoList(list);
+    const out = cleanTodoList(list);
+    const [moved] = out.splice(fromAt, 1);
+    out.splice(toAt, 0, moved);
+    return out;
+}
+// Serialize the live list for a session save: a deep copy (the save must
+// never alias live state). Total: never throws; unserializable input reads
+// as an empty list.
+export function serializeTodosForPersist(list) {
+    try {
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const item of list) {
+            const clean = validateTodoRecord(item);
+            if (!clean)
+                return [];
+            const persisted = {
+                content: clean.content,
+                status: clean.status,
+            };
+            if (clean.priority !== undefined)
+                persisted.priority = clean.priority;
+            if (clean.activeForm !== undefined)
+                persisted.activeForm = clean.activeForm;
+            out.push(persisted);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+// Restore a saved list: valid items come back verbatim (states intact, order
+// intact); a missing key, a non-array, or ANY malformed item degrades to an
+// empty list — never a throw, never a partial list (a half-restored plan is
+// worse than a visibly empty one). Old records without the todos key land
+// here safely.
+export function restoreTodosFromPersist(value) {
+    try {
+        if (value === null || value === undefined)
+            return [];
+        if (!Array.isArray(value))
+            return [];
+        const out = [];
+        for (const item of value) {
+            const clean = validateTodoRecord(item);
+            if (!clean)
+                return [];
+            out.push(clean);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+// Read the checklist out of a session record's metadata (the switch-restore
+// path): absent or corrupt reads as []. Never throws.
+export function readSessionTodos(metadata) {
+    try {
+        if (!isRecord(metadata))
+            return [];
+        return restoreTodosFromPersist(metadata[TODOS_METADATA_KEY]);
+    }
+    catch {
+        return [];
+    }
+}
+// Stamp the checklist into a metadata object for an updateSession patch (the
+// per-turn persist path): every other key (extension state, filediffs, …)
+// passes through untouched — only metadata.todos is set. Never throws.
+export function withSessionTodos(metadata, list) {
+    try {
+        const base = isRecord(metadata)
+            ? { ...metadata }
+            : {};
+        base[TODOS_METADATA_KEY] = serializeTodosForPersist(list);
+        return base;
+    }
+    catch {
+        return { [TODOS_METADATA_KEY]: [] };
+    }
+}

package/dist/tools/filesystem.js

@@ -2,12 +2,13 @@
 // bytes first (see snapshots.ts); validation failures return before capture.
 import { promises as fsp } from "node:fs";
 import * as path from "node:path";
+import { MEDIA_MAX_BYTES, mediaDescriptor, oversizeImageError, saveMedia, sniffImageMime, sniffPdf, unsupportedBinaryError, } from "../media.js";
 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, truncateHead } from "./shared.js";
+import { err, invalidCall, READ_CHAR_CAP, READ_FILE_MAX_BYTES, 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 {
@@ -26,6 +27,62 @@ 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")}`;
         }
+        // Vision-input peek FIRST: image magic bytes sit in the first 12 bytes,
+        // so every file is classified with one tiny read. Supported images
+        // (PNG/JPEG/GIF/WebP) take the media path with their own MEDIA_MAX_BYTES
+        // cap; PDF magic gets convert-first guidance at any size; everything
+        // else falls into the existing guarded text path untouched.
+        const fileSize = st.size ?? 0;
+        let peek = null;
+        try {
+            const fh = await fsp.open(r.abs, "r");
+            try {
+                const buf = Buffer.alloc(12);
+                const { bytesRead } = await fh.read(buf, 0, 12, 0);
+                peek = buf.subarray(0, bytesRead);
+            }
+            finally {
+                await fh.close();
+            }
+        }
+        catch {
+            // peek never breaks reads — null falls through to the text path
+        }
+        if (peek !== null) {
+            const mime = sniffImageMime(peek);
+            if (mime !== null) {
+                if (fileSize > MEDIA_MAX_BYTES)
+                    return oversizeImageError(args.path, fileSize);
+                let raw;
+                try {
+                    raw = await fsp.readFile(r.abs);
+                }
+                catch {
+                    return err(`cannot read file: ${args.path}`);
+                }
+                const { id } = await saveMedia(raw, mime, args.path);
+                // Fingerprint on the utf8 decoding so a later edit compares
+                // consistently with editTool's own read+hash.
+                readFingerprints.set(fingerprintKey(r.abs), contentHash(raw.toString("utf8")));
+                return (`Image read successfully: ${args.path} (${mime}, ${raw.length} bytes, attached as vision input).\n` +
+                    mediaDescriptor(id, mime, raw.length));
+            }
+            if (sniffPdf(peek)) {
+                return unsupportedBinaryError(args.path, "pdf", fileSize);
+            }
+        }
+        // OOM guard: never materialize a whole file past READ_FILE_MAX_BYTES
+        // (UTF-16 doubling + split/join copies can OOM the heap on one read).
+        // The size is known from the stat above, so this costs no extra I/O.
+        try {
+            const size = st.size ?? 0;
+            if (size > READ_FILE_MAX_BYTES) {
+                return err(`file too large to read (${size} bytes > 1MB): ${args.path}. Narrow with grep/glob first`);
+            }
+        }
+        catch {
+            // size check never breaks reads (the read below still applies its cap)
+        }
         // 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.
@@ -48,32 +105,42 @@ export async function readTool(args, cwd = process.cwd()) {
         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;
-            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;
+        return readTextResult(r.abs, args, text, st, normOffset, normLimit);
     }
     catch (e) {
         return err(e instanceof Error ? e.message : String(e));
     }
 }
+// Shared text path for readTool: fingerprint + line window + 64KB cap +
+// cache store. The small-file caller reuses its already-read bytes;
+// the over-cap caller arrives here after the media peek.
+function readTextResult(abs, args, text, st, normOffset, normLimit) {
+    const stat = st;
+    const hash = contentHash(text);
+    readFingerprints.set(fingerprintKey(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;
+        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: stat.mtimeMs ?? 0, size: stat.size ?? 0 };
+        const { offset: o, limit: l } = normOffset !== undefined && normLimit !== undefined
+            ? { offset: normOffset, limit: normLimit }
+            : normalizeReadWindow(args.offset, args.limit);
+        setCachedRead(abs, o, l, out, statInfo, hash);
+    }
+    catch {
+        // cache store never breaks reads
+    }
+    return out;
+}
 export async function writeTool(args, cwd = process.cwd()) {
     try {
         const r = resolveSandbox(args?.path, cwd);
@@ -110,6 +177,19 @@ export async function editTool(args, cwd = process.cwd()) {
         }
         if (typeof args.newString !== "string")
             return err("newString must be a string");
+        // OOM guard (same rationale as readTool above): an edit materializes
+        // the whole file plus split/join copies, so refuse past the cap with
+        // guidance instead of risking the heap. Missing paths keep the legacy
+        // "no such file" error below.
+        try {
+            const st = await fsp.stat(r.abs);
+            if (st.isFile() && st.size > READ_FILE_MAX_BYTES) {
+                return err(`file too large to edit (${st.size} bytes > 1MB): ${args.path}. Use bash for targeted changes to huge files`);
+            }
+        }
+        catch {
+            // stat failure falls through to the read below (missing → its error)
+        }
         let text;
         try {
             text = await fsp.readFile(r.abs, "utf8");