@sema-agent/core 5.1.0 → 5.2.0

package/dist/stores/file/file-snapshot-store.js

@@ -18,7 +18,8 @@ export class FileFileSnapshotStore {
     }
     inFlightKey;
     bounds;
-    constructor(root, bounds) {
+    onCorruptRead;
+    constructor(root, bounds, opts) {
         this.base = join(root, "file-snapshots");
         this.blobsDir = join(this.base, "blobs");
         this.manifestsDir = join(this.base, "manifests");
@@ -30,6 +31,14 @@ export class FileFileSnapshotStore {
             maxBytes: bounds?.maxBytes ?? DEFAULT_SNAPSHOT_BOUNDS.maxBytes,
             ignoreDirs: new Set(bounds?.ignoreDirs ?? DEFAULT_SNAPSHOT_BOUNDS.ignoreDirs),
         };
+        this.onCorruptRead = opts?.onCorruptRead;
+    }
+    disclose(path, reason) {
+        try {
+            this.onCorruptRead?.({ path, reason });
+        }
+        catch {
+        }
     }
     scopeDir(scope) {
         return join(this.manifestsDir, sanitizeScope(scope));
@@ -60,9 +69,13 @@ export class FileFileSnapshotStore {
         }
         try {
             const parsed = JSON.parse(raw);
-            return Array.isArray(parsed) ? new Map(parsed) : null;
+            if (Array.isArray(parsed))
+                return new Map(parsed);
+            this.disclose(path, "manifest is not a pair array — read as no snapshot");
+            return null;
         }
         catch {
+            this.disclose(path, "unparseable manifest JSON (torn/zero-byte write?) — read as no snapshot");
             return null;
         }
     }
@@ -132,6 +145,7 @@ export class FileFileSnapshotStore {
         catch (err) {
             if (err.code === "ENOENT")
                 return [];
+            this.disclose(dir, `manifest scope directory unreadable (${err.code ?? "unknown"}) — listed as no keys`);
             return [];
         }
         return entries
@@ -242,8 +256,10 @@ export class FileFileSnapshotStore {
         catch (err) {
             if (err.code === "ENOENT")
                 entries = [];
-            else
+            else {
                 entries = [];
+                this.disclose(dir, `manifest scope directory unreadable (${err.code ?? "unknown"}) — the manifest-deletion pass was skipped`);
+            }
         }
         for (const file of entries) {
             if (!file.endsWith(".json"))
@@ -266,8 +282,10 @@ export class FileFileSnapshotStore {
         catch (err) {
             if (err.code === "ENOENT")
                 scopeDirs = [];
-            else
+            else {
+                this.disclose(this.manifestsDir, `manifest root unreadable (${err.code ?? "unknown"}) — blob GC aborted, every blob kept`);
                 return removed;
+            }
         }
         for (const scopeName of scopeDirs) {
             const sdir = join(this.manifestsDir, scopeName);
@@ -279,6 +297,7 @@ export class FileFileSnapshotStore {
                 if (err.code === "ENOENT")
                     continue;
                 complete = false;
+                this.disclose(sdir, `manifest scope directory unreadable (${err.code ?? "unknown"}) — blob GC aborted, every blob kept`);
                 break;
             }
             for (const file of files) {
@@ -287,6 +306,7 @@ export class FileFileSnapshotStore {
                 const m = this.readManifest(join(sdir, file));
                 if (!m) {
                     complete = false;
+                    this.disclose(join(sdir, file), "manifest unreadable during the live-set scan — blob GC aborted, every blob kept");
                     break;
                 }
                 for (const h of m.values())
@@ -301,7 +321,10 @@ export class FileFileSnapshotStore {
         try {
             blobs = readdirSync(this.blobsDir);
         }
-        catch {
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                this.disclose(this.blobsDir, `blob directory unreadable (${err.code ?? "unknown"}) — blob GC skipped, every blob kept`);
+            }
             return removed;
         }
         for (const blob of blobs) {

package/dist/stores/file/fs-atomic.d.ts

@@ -4,7 +4,10 @@ export declare function resolveDataRoot(explicit?: string): string;
 export declare function writeThenLink(target: string, content: string | Uint8Array): void;
 export declare function ensureDir(dir: string): void;
 export declare function atomicWriteFile(tmpDir: string, target: string, bytes: string): void;
-export declare function readJsonlRecords<T>(path: string): T[];
+export declare function readJsonlRecords<T>(path: string, onCorrupt?: (info: {
+    path: string;
+    reason: string;
+}) => void): T[];
 export declare function canonicalStoreKey(p: string): string;
 export declare class AppendLog {
     private fd;

package/dist/stores/file/fs-atomic.js

@@ -101,7 +101,7 @@ function basenameOf(p) {
 function dirnameOf(p) {
     return dirname(p);
 }
-export function readJsonlRecords(path) {
+export function readJsonlRecords(path, onCorrupt) {
     let raw;
     try {
         raw = readFileSync(path, "utf8");
@@ -126,6 +126,7 @@ export function readJsonlRecords(path) {
             out.push(JSON.parse(line));
         }
         catch {
+            onCorrupt?.({ path, reason: `unparseable jsonl record at line ${i + 1} (skipped; the rest of the replay is intact)` });
         }
     }
     return out;

package/dist/stores/file/index.d.ts

@@ -9,10 +9,10 @@ import type { FileSnapshotStore } from "../../core/file-snapshot-store.js";
 import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
 export { FileCheckpointStore, type FileCheckpointStoreOptions } from "./checkpoint-store.js";
 export { FileMemoryStore } from "./memory-store.js";
-export { FileSessionRepo } from "./session-store.js";
+export { FileSessionRepo, type FileSessionRepoOptions } from "./session-store.js";
 export { FileToolResultStore } from "./tool-result-store.js";
-export { FileSessionPolicyStore } from "./session-policy-store.js";
-export { FileFileSnapshotStore } from "./file-snapshot-store.js";
+export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type SessionPolicyCorruptReadInfo } from "./session-policy-store.js";
+export { FileFileSnapshotStore, type FileFileSnapshotStoreOptions } from "./file-snapshot-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
@@ -23,6 +23,13 @@ export interface FileStorageBackendOptions {
     checkpoint?: FileCheckpointStoreOptions;
     snapshotBounds?: Partial<import("../../core/file-snapshot-store.js").FileSnapshotBounds>;
     embedder?: import("../../core/memory.js").Embedder;
+    onCorruptRead?: (info: FileStorageCorruptReadInfo) => void;
+}
+export interface FileStorageCorruptReadInfo {
+    path: string;
+    reason: string;
+    sessionId?: string;
+    principal?: string;
 }
 export declare class FileStorageBackend {
     readonly root: string;

package/dist/stores/file/index.js

@@ -39,7 +39,8 @@ export class FileStorageBackend {
         this.lock = new BootLock(join(this.root, "LOCK"));
         this.lock.acquire();
         try {
-            const repo = new FileSessionRepo(this.root);
+            const corruptRead = opts.onCorruptRead !== undefined ? { onCorruptRead: opts.onCorruptRead } : undefined;
+            const repo = new FileSessionRepo(this.root, corruptRead);
             this.fileSessions = repo;
             this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget" });
             this.sessionStore = this.ttl;
@@ -48,8 +49,8 @@ export class FileStorageBackend {
             this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});
             this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
             this.toolResultStore = new FileToolResultStore(this.root);
-            this.sessionPolicyStore = new FileSessionPolicyStore(this.root);
-            this.fileSnapshotStore = new FileFileSnapshotStore(this.root, opts.snapshotBounds);
+            this.sessionPolicyStore = new FileSessionPolicyStore(this.root, corruptRead);
+            this.fileSnapshotStore = new FileFileSnapshotStore(this.root, opts.snapshotBounds, corruptRead);
             this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root);
             this.workflowJournalStore = this.fileWorkflowJournal;
             this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));

package/dist/stores/file/mailbox-store.d.ts

@@ -2,6 +2,10 @@ import { type MailboxAppendMessage, type MailboxLease, type MailboxStore } from
 export interface FileMailboxStoreOptions {
     fsync?: boolean;
     compactEvery?: number;
+    onCorruptRead?: (info: {
+        path: string;
+        reason: string;
+    }) => void;
 }
 export declare class FileMailboxStore implements MailboxStore {
     private readonly dir;
@@ -9,6 +13,7 @@ export declare class FileMailboxStore implements MailboxStore {
     private readonly fsyncEnabled;
     private readonly compactEvery;
     private readonly touched;
+    private readonly discloseCorrupt;
     constructor(root: string, opts?: FileMailboxStoreOptions);
     private boxPath;
     private lockKey;

package/dist/stores/file/mailbox-store.js

@@ -39,9 +39,21 @@ export class FileMailboxStore {
     fsyncEnabled;
     compactEvery;
     touched = new Map();
+    discloseCorrupt;
     constructor(root, opts = {}) {
         this.fsyncEnabled = opts.fsync !== false;
         this.compactEvery = opts.compactEvery ?? 500;
+        const sink = opts.onCorruptRead;
+        this.discloseCorrupt =
+            sink === undefined
+                ? undefined
+                : (info) => {
+                    try {
+                        sink(info);
+                    }
+                    catch {
+                    }
+                };
         const lexicalDir = resolve(join(root, "mailboxes"));
         const lexicalTmp = resolve(join(root, "tmp"));
         ensureDir(lexicalDir);
@@ -67,7 +79,7 @@ export class FileMailboxStore {
             return b;
         }
         ensureDir(join(this.dir, sanitizeScope(scope)));
-        const events = readJsonlRecords(path);
+        const events = readJsonlRecords(path, this.discloseCorrupt);
         const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path };
         for (const ev of events)
             applyEvent(state, ev);
@@ -145,7 +157,7 @@ export class FileMailboxStore {
             return 0;
         return withPathLock(this.lockKey(scope, handle), () => {
             const b = { messages: [], nextSeq: 1 };
-            for (const ev of readJsonlRecords(path))
+            for (const ev of readJsonlRecords(path, this.discloseCorrupt))
                 applyEvent(b, ev);
             return b.messages.length;
         });
@@ -200,7 +212,7 @@ export class FileMailboxStore {
                 if (sharedBoxes.has(key))
                     return false;
                 const b = { messages: [], nextSeq: 1 };
-                for (const ev of readJsonlRecords(path))
+                for (const ev of readJsonlRecords(path, this.discloseCorrupt))
                     applyEvent(b, ev);
                 const newest = newestSentAt(b.messages);
                 if (newest === undefined || newest >= now - maxAgeMs)

package/dist/stores/file/session-policy-store.d.ts

@@ -1,15 +1,18 @@
 import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "../../core/session-policy-store.js";
+export interface SessionPolicyCorruptReadInfo {
+    sessionId: string;
+    principal?: string;
+    path: string;
+    reason: string;
+}
+export interface FileSessionPolicyStoreOptions {
+    onCorruptRead?: (info: SessionPolicyCorruptReadInfo) => void;
+}
 export declare class FileSessionPolicyStore implements SessionPolicyStore {
     private readonly dir;
     private readonly onCorruptRead;
-    constructor(root: string, opts?: {
-        onCorruptRead?: (info: {
-            sessionId: string;
-            principal?: string;
-            path: string;
-            reason: string;
-        }) => void;
-    });
+    constructor(root: string, opts?: FileSessionPolicyStoreOptions);
+    private disclose;
     private discloseCorrupt;
     private pathFor;
     private read;

package/dist/stores/file/session-policy-store.js

@@ -10,13 +10,16 @@ export class FileSessionPolicyStore {
         ensureDir(this.dir);
         this.onCorruptRead = opts?.onCorruptRead;
     }
-    discloseCorrupt(sessionId, principal, reason) {
+    disclose(info) {
         try {
-            this.onCorruptRead?.({ sessionId, ...(principal !== undefined ? { principal } : {}), path: this.pathFor(sessionId, principal), reason });
+            this.onCorruptRead?.(info);
         }
         catch {
         }
     }
+    discloseCorrupt(sessionId, principal, reason) {
+        this.disclose({ sessionId, ...(principal !== undefined ? { principal } : {}), path: this.pathFor(sessionId, principal), reason });
+    }
     pathFor(sessionId, principal) {
         const composite = JSON.stringify([sessionId, principal ?? null]);
         return join(this.dir, `${sanitizeScope(composite)}.json`);
@@ -90,15 +93,29 @@ export class FileSessionPolicyStore {
         for (const file of files) {
             if (!file.endsWith(".json"))
                 continue;
+            const full = join(this.dir, file);
+            let raw;
+            try {
+                raw = readFileSync(full, "utf8");
+            }
+            catch (err) {
+                if (err.code !== "ENOENT") {
+                    this.disclose({ sessionId, path: full, reason: `read failed (non-ENOENT): ${err.message}` });
+                }
+                continue;
+            }
             let parsed;
             try {
-                parsed = JSON.parse(readFileSync(join(this.dir, file), "utf8"));
+                parsed = JSON.parse(raw);
             }
             catch {
+                this.disclose({ sessionId, path: full, reason: "unparseable JSON (torn/zero-byte write?)" });
                 continue;
             }
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                this.disclose({ sessionId, path: full, reason: "not a JSON object" });
                 continue;
+            }
             const r = parsed;
             if (r.__sid !== sessionId)
                 continue;

package/dist/stores/file/session-store.d.ts

@@ -1,9 +1,17 @@
 import type { Session, SessionForkOptions, SessionMetadata, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
+export interface FileSessionRepoOptions {
+    onCorruptRead?: (info: {
+        path: string;
+        reason: string;
+    }) => void;
+}
 export declare class FileSessionRepo implements SessionRepo {
     private readonly dir;
     private readonly tmpDir;
+    private readonly onCorruptRead;
     private readonly joined;
-    constructor(root: string);
+    constructor(root: string, opts?: FileSessionRepoOptions);
+    private disclose;
     private pathFor;
     private read;
     private storage;

package/dist/stores/file/session-store.js

@@ -54,12 +54,21 @@ class FileSessionStorage extends BaseSessionStorage {
 export class FileSessionRepo {
     dir;
     tmpDir;
+    onCorruptRead;
     joined = new Map();
-    constructor(root) {
+    constructor(root, opts) {
         this.dir = join(root, "sessions");
         this.tmpDir = join(root, "tmp");
         ensureDir(this.dir);
         ensureDir(this.tmpDir);
+        this.onCorruptRead = opts?.onCorruptRead;
+    }
+    disclose(path, reason) {
+        try {
+            this.onCorruptRead?.({ path, reason });
+        }
+        catch {
+        }
     }
     pathFor(id) {
         return join(this.dir, `${sanitizePathComponent(id)}${SUFFIX}`);
@@ -69,7 +78,7 @@ export class FileSessionRepo {
         if (!existsSync(path)) {
             throw new SessionError("not_found", `Session not found: ${id}`);
         }
-        const lines = readJsonlRecords(path);
+        const lines = readJsonlRecords(path, (info) => this.disclose(info.path, info.reason));
         let createdAt = "";
         let forkedFrom;
         const entries = [];
@@ -132,7 +141,10 @@ export class FileSessionRepo {
         try {
             names = readdirSync(this.dir);
         }
-        catch {
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — listed as empty`);
+            }
             return [];
         }
         const out = [];
@@ -144,7 +156,10 @@ export class FileSessionRepo {
                 const { createdAt, forkedFrom } = this.read(id);
                 out.push({ id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) });
             }
-            catch {
+            catch (err) {
+                if (!(err instanceof SessionError && err.code === "not_found")) {
+                    this.disclose(this.pathFor(id), `session log unreadable (${err instanceof Error ? err.message : String(err)}) — skipped from the listing`);
+                }
             }
         }
         return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));

package/dist/tools/fs/fs-search-tools.js

@@ -40,6 +40,15 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
         }),
         effect: "read",
         execute: async (args, ctx) => {
+            const retired = args;
+            for (const [name, repair] of [
+                ["regex", "the `pattern` is ALWAYS evaluated as a regular expression (ripgrep semantics) — drop the key; to match text literally, escape the regex metacharacters in `pattern`"],
+                ["max_results", "cap the result count with `head_limit` (0 = unlimited), paginating with `offset`"],
+            ]) {
+                if (retired[name] !== undefined) {
+                    return errorResult(`Error (Grep): \`${name}\` is not a Grep parameter (retired) — ${repair}. Nothing was searched.`);
+                }
+            }
             const a = args;
             for (const [name, value] of [
                 ["head_limit", a.head_limit],

package/dist/tools/fs/fs-shared.d.ts

@@ -42,7 +42,7 @@ export declare function bashTimeoutCapsSec(caps: {
 };
 export declare function bashMaxOutputChars(): number;
 export declare const FILE_PATH_PARAMS: {
-    file_path: Type.TOptional<Type.TString>;
+    file_path: Type.TString;
 };
 export declare function clipShellOutput(s: string): string;
 export declare function writeShellOverflowFile(env: ExecutionEnv, stdout: string, stderr: string): Promise<string | undefined>;

package/dist/tools/fs/fs-shared.js

@@ -76,7 +76,7 @@ export function bashMaxOutputChars() {
     return Math.min(Math.floor(raw), BASH_MAX_OUTPUT_CHARS_CEILING);
 }
 export const FILE_PATH_PARAMS = {
-    file_path: Type.Optional(Type.String({ description: "File path (within the configured root)." })),
+    file_path: Type.String({ description: "File path (within the configured root)." }),
 };
 export function clipShellOutput(s) {
     return clipWithFilePointer(s, bashMaxOutputChars());

package/dist/tools/todo.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { errorResult } from "../core/tools.js";
 export function createTodoWriteTool() {
     let todos = [];
     return {
@@ -6,7 +7,7 @@ export function createTodoWriteTool() {
         contract: { contractId: "core.todo_write@1", implementationRevision: "1" },
         description: "Create and update a task list for the current session. The list is rendered to the user as your working plan.\n" +
             "\n" +
-            '- Each todo has `content`, `status` ("pending" | "in_progress" | "completed"), and optionally `activeForm` (present-tense label shown while in progress).\n' +
+            '- Each todo has `content`, `status` ("pending" | "in_progress" | "completed"), and `activeForm` (present-tense label shown while in progress).\n' +
             "- Send the full list each call; it replaces the previous one.\n" +
             "- Keep one item `in_progress` at a time and mark it `completed` when done.",
         descriptionClassic: "Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.\n" +
@@ -81,13 +82,19 @@ export function createTodoWriteTool() {
         }),
         effect: "idempotent",
         execute: (args) => {
-            const shape = (t) => ({
-                content: t.content,
-                status: t.status,
-                activeForm: t.activeForm && t.activeForm.length > 0 ? t.activeForm : t.content,
-            });
+            const shape = (t) => ({ content: t.content, status: t.status, activeForm: t.activeForm });
             const oldTodos = todos.map(shape);
             const written = args.todos;
+            for (let i = 0; i < written.length; i++) {
+                const activeForm = written[i].activeForm;
+                if (typeof activeForm !== "string" || activeForm.length === 0) {
+                    const what = activeForm === undefined ? "is missing" : "has an empty or non-string";
+                    return errorResult(`Error (TodoWrite): todo ${i + 1} of ${written.length} ${what} \`activeForm\` — every todo needs the ` +
+                        `present-continuous label shown while it runs (e.g. content "Run the tests" → activeForm "Running the ` +
+                        `tests"), alongside its imperative \`content\`. Nothing was stored; resend the COMPLETE list with the ` +
+                        `label filled in on every item.`);
+                }
+            }
             const allDone = written.every((t) => t.status === "completed");
             todos = allDone ? [] : written;
             const newTodos = written.map(shape);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",