agent-lyceum 0.22.0 → 0.24.0

package/dist/adapters/claude.d.ts

@@ -1,7 +1,12 @@
+import { type WritePolicy } from "../policy.js";
 import type { ResolvedAgent, ResolvedProject } from "../config.js";
 import type { ErrorKind } from "../schema.js";
 import type { Invocation, WakeInput } from "./types.js";
-export declare function buildClaudeSettings(project: ResolvedProject, agent: ResolvedAgent): Record<string, unknown>;
+/** `override`: a policy that replaces the agent's own; `cwd` is then the (scratch) directory the runtime starts in, in place of the repo. */
+export declare function buildClaudeSettings(project: ResolvedProject, agent: ResolvedAgent, override?: {
+    policy: WritePolicy;
+    cwd: string;
+}): Record<string, unknown>;
 export declare function buildClaudeInvocation(input: WakeInput): Invocation;
 /**
  * The text the rules read: the result message (only when it is an error message: pass `result` for an `is_error` run), stderr, and the HTTP status

package/dist/adapters/claude.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { repoDirFor, writePolicy } from "../policy.js";
+import { repoDirFor, scratchCwd, writePolicy } from "../policy.js";
 /** Claude Code path rules: `//abs/path` — a leading "/" plus the absolute path. */
 const rule = (tool, p) => `${tool}(/${p})`;
 function denyRules(p) {
@@ -17,10 +17,11 @@ function denyRules(p) {
         out.push(rule("Edit", `${p}/**`));
     return out;
 }
-export function buildClaudeSettings(project, agent) {
-    const pol = writePolicy(project, agent);
-    const ws = project.workspaces?.[agent.name];
-    const repo = repoDirFor(project, agent.name);
+/** `override`: a policy that replaces the agent's own; `cwd` is then the (scratch) directory the runtime starts in, in place of the repo. */
+export function buildClaudeSettings(project, agent, override) {
+    const pol = override?.policy ?? writePolicy(project, agent);
+    const ws = override ? undefined : project.workspaces?.[agent.name];
+    const repo = override?.cwd ?? repoDirFor(project, agent.name);
     const allow = ["Bash", "Read", "Glob", "Grep"];
     // Web tools are opt-in: `search` is the lighter one (snippets only), `fetch` also pulls whole pages into the agent's context.
     if (agent.allowWeb === "search" || agent.allowWeb === "fetch")
@@ -41,7 +42,7 @@ export function buildClaudeSettings(project, agent) {
             enabled: true,
             allowUnsandboxedCommands: false,
             filesystem: {
-                allowWrite: [ws?.root ?? project.dir, ...pol.allowDirs, ...pol.allowFiles],
+                allowWrite: [override?.cwd ?? ws?.root ?? project.dir, ...pol.allowDirs, ...pol.allowFiles],
                 denyWrite: pol.deny,
             },
         },
@@ -52,10 +53,13 @@ export function buildClaudeInvocation(input) {
     fs.mkdirSync(workDir, { recursive: true });
     const settingsFile = path.join(workDir, "claude-settings.json");
     const systemFile = path.join(workDir, "system-prompt.md");
-    fs.writeFileSync(settingsFile, JSON.stringify(buildClaudeSettings(project, agent), null, 2));
+    const repo = input.policy ? scratchCwd(workDir) : repoDirFor(project, agent.name);
+    const scope = input.policy ? { policy: input.policy, cwd: repo } : undefined;
+    if (scope)
+        fs.mkdirSync(repo, { recursive: true });
+    fs.writeFileSync(settingsFile, JSON.stringify(buildClaudeSettings(project, agent, scope), null, 2));
     fs.writeFileSync(systemFile, input.systemPrompt);
-    const pol = writePolicy(project, agent);
-    const repo = repoDirFor(project, agent.name);
+    const pol = input.policy ?? writePolicy(project, agent);
     const addDirs = [...pol.allowDirs, ...pol.readDirs, ...pol.allowFiles.map((f) => path.dirname(f))].filter((d) => !(d === repo || d.startsWith(repo + path.sep)));
     const args = [
         "-p",

package/dist/adapters/codex.js

@@ -1,9 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { repoDirFor, writePolicy } from "../policy.js";
+import { repoDirFor, scratchCwd, writePolicy } from "../policy.js";
 export function codexWritableRoots(input) {
-    const pol = writePolicy(input.project, input.agent);
-    const work = repoDirFor(input.project, input.agent.name);
+    const pol = input.policy ?? writePolicy(input.project, input.agent);
+    const work = input.policy ? scratchCwd(input.workDir) : repoDirFor(input.project, input.agent.name);
     const roots = [...pol.allowDirs, ...pol.allowFiles.map((f) => path.dirname(f))].filter((d) => !(d === work || d.startsWith(work + path.sep)));
     return [...new Set(roots)];
 }
@@ -52,8 +52,10 @@ export function codexOutputTokens(jsonl) {
 const CODEX_WEB_SEARCH = { none: "disabled", search: "cached", fetch: "live" };
 export function buildCodexInvocation(input) {
     const { project, agent, workDir } = input;
-    const repo = repoDirFor(project, agent.name);
+    const repo = input.policy ? scratchCwd(workDir) : repoDirFor(project, agent.name);
     fs.mkdirSync(workDir, { recursive: true });
+    if (input.policy)
+        fs.mkdirSync(repo, { recursive: true });
     const lastFile = path.join(workDir, "codex-last-message.txt");
     const roots = codexWritableRoots(input);
     const common = [

package/dist/adapters/types.d.ts

@@ -1,5 +1,6 @@
 import type { ErrorKind } from "../schema.js";
 import type { ResolvedAgent, ResolvedProject } from "../config.js";
+import type { WritePolicy } from "../policy.js";
 import type { AgentWorkspace } from "../worktree.js";
 export interface WakeInput {
     project: ResolvedProject;
@@ -16,6 +17,11 @@ export interface WakeInput {
     signal?: AbortSignal;
     /** Where the full stdout/stderr of this invocation are written. */
     logDir?: string;
+    /**
+     * Replaces the agent's normal write policy (memory tidy: only the dirs being tidied). The repo is then not writable
+     * either: the runtime starts in an empty scratch dir inside `workDir` and may only read the repo.
+     */
+    policy?: WritePolicy;
 }
 export interface WakeResult {
     ok: boolean;

package/dist/call.js

@@ -43,7 +43,6 @@ export function callProject(home, agent, dir, callDir) {
         config: path.join(callDir, "call.yaml"),
         agentsDir: path.join(callDir, "agents"),
         shared: path.join(callDir, "shared"),
-        common: path.join(callDir, "shared", "COMMON.md"),
         inboxRoot: path.join(callDir, "mail", "inbox"),
         outboxRoot: path.join(callDir, "mail", "outbox"),
         runs: path.join(callDir, "runs"),

package/dist/cli.js

@@ -693,7 +693,11 @@ program
                     console.log(`  restored  ${f}`);
                 for (const s of r.skipped)
                     console.log(`  skipped   ${s.rel}: ${s.reason}`);
-                if (!r.restored.length && !r.skipped.length)
+                for (const f of r.records?.restored ?? [])
+                    console.log(`  restored  records/${f}`);
+                for (const k of r.records?.skipped ?? [])
+                    console.log(`  skipped   records/${k.rel}: ${k.reason}`);
+                if (!r.restored.length && !r.skipped.length && !r.records?.restored.length && !r.records?.skipped.length)
                     console.log(`Archive ${opts.undo} holds no files to restore.`);
             }
             finally {
@@ -728,11 +732,11 @@ program
             console.log(`No agent has ${layer} memory configured. ${layer === "project" ? "The template gives agents global memory only: set `memory.project` for an agent in project.yaml (or tidy global memory with --layer global)." : "Set `memory.global` for an agent."}`);
         for (const r of results) {
             if (r.status === "tidied")
-                console.log(`  ${r.agent} (${r.layer}): tidied. Archive: ${path.join(r.dir, ".archive", r.archive ?? "")} — undo with: agent-lyceum tidy --undo ${r.archive} -p ${pr.name} --agent ${r.agent}${r.layer === "global" ? " --layer global" : ""}`);
+                console.log(`  ${r.agent} (${r.layer}): tidied. Archive: ${path.join(r.dir, ".archive", r.archive ?? "")}${r.recordsDir && r.recordsDir !== r.dir ? `, records: ${path.join(r.recordsDir, ".archive", r.archive ?? "")}` : ""} — undo with: agent-lyceum tidy --undo ${r.archive} -p ${pr.name} --agent ${r.agent}${r.layer === "global" ? " --layer global" : ""}`);
             else if (r.status === "skipped")
                 console.log(`  ${r.agent} (${r.layer}): skipped — ${r.problems.join("; ")}`);
             else if (r.status === "failed") {
-                console.error(`  ${r.agent} (${r.layer}): FAILED, memory restored to how it was`);
+                console.error(`  ${r.agent} (${r.layer}): FAILED, ${r.recordsDir === r.dir ? "project records" : r.recordsDir ? "memory and project records" : "memory"} restored to how it was`);
                 for (const p of r.problems)
                     console.error(`    - ${p}`);
             }

package/dist/doctor.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { findOnPath } from "./fs-util.js";
 import { tidyAdvice } from "./memory-tidy.js";
+import { listRecords, RECORD_KINDS } from "./records.js";
 import { listRunLocks, listUnreadableRunLocks, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
@@ -169,6 +170,17 @@ export async function diagnoseProject(project, opts = {}) {
     }
     for (const a of tidyAdvice(project))
         checks.push({ level: "info", subject: "memory", message: `${a.agent}: ${a.reason}. Consider: agent-lyceum tidy -p ${project.name} --agent ${a.agent} (doctor only suggests; it never tidies).` });
+    for (const kind of RECORD_KINDS) {
+        const recs = listRecords(project, kind);
+        const ids = new Set(recs.map((r) => r.id));
+        for (const r of recs) {
+            if (r.invalid)
+                checks.push({ level: "warn", subject: "records", message: `${r.file}: ${r.invalid}` });
+            for (const s of r.supersedes)
+                if (!ids.has(s))
+                    checks.push({ level: "warn", subject: "records", message: `${r.file}: supersedes "${s}", but no ${kind} entry has that id.` });
+        }
+    }
     const runtimes = await probeProjectRuntimes(project, opts, true);
     checks.push(...judgeRuntimes(project, runtimes));
     checks.push({ level: "info", subject: "login", message: "Login status is unknown: agent-lyceum does not read credentials, and the CLIs offer no read-only login check it can rely on." });

package/dist/fs-util.d.ts

@@ -10,3 +10,26 @@ export declare function readFileCapped(file: string, limit: number): {
     text: string;
     truncated: boolean;
 } | undefined;
+/**
+ * The bytes of a regular file, opened without following a symlink and without blocking (a FIFO opens at once and fails the
+ * fstat check). undefined for anything else or on any error: never throws, never hangs.
+ */
+export declare function readRegularFileNoFollow(file: string): Buffer | undefined;
+/** `buf` cut to at most `limit` bytes, backed up to a character boundary so a multi-byte character is never split. */
+export declare function cutUtf8(buf: Buffer, limit: number): Buffer;
+/** `buf` without a trailing incomplete UTF-8 sequence (a cut-off lead byte and its continuation bytes). */
+export declare function trimPartialUtf8(buf: Buffer): Buffer;
+export type CappedRead = {
+    ok: true;
+    buf: Buffer;
+    size: number;
+    truncated: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Up to `limit` bytes of a regular file, opened without following a symlink and without blocking; reads at most `limit + 1` bytes.
+ * `size` is the file's size from fstat. Never throws: a refusal says why, from the one open (`symlink`, `not_regular`, `open_error:<code>`).
+ */
+export declare function readRegularFileCappedNoFollow(file: string, limit: number): CappedRead;

package/dist/fs-util.js

@@ -58,3 +58,81 @@ export function readFileCapped(file, limit) {
         }
     }
 }
+/**
+ * The bytes of a regular file, opened without following a symlink and without blocking (a FIFO opens at once and fails the
+ * fstat check). undefined for anything else or on any error: never throws, never hangs.
+ */
+export function readRegularFileNoFollow(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+        if (!fs.fstatSync(fd).isFile())
+            return undefined;
+        return fs.readFileSync(fd);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { }
+        }
+    }
+}
+/** `buf` cut to at most `limit` bytes, backed up to a character boundary so a multi-byte character is never split. */
+export function cutUtf8(buf, limit) {
+    if (buf.length <= limit)
+        return buf;
+    let cut = limit;
+    while (cut > 0 && ((buf[cut] ?? 0) & 0xc0) === 0x80)
+        cut--;
+    return buf.subarray(0, cut);
+}
+/** `buf` without a trailing incomplete UTF-8 sequence (a cut-off lead byte and its continuation bytes). */
+export function trimPartialUtf8(buf) {
+    for (let i = 1; i <= Math.min(3, buf.length); i++) {
+        const b = buf[buf.length - i];
+        if ((b & 0xc0) === 0x80)
+            continue;
+        const need = b >= 0xf0 ? 4 : b >= 0xe0 ? 3 : b >= 0xc0 ? 2 : 1;
+        return need > i ? buf.subarray(0, buf.length - i) : buf;
+    }
+    return buf;
+}
+/**
+ * Up to `limit` bytes of a regular file, opened without following a symlink and without blocking; reads at most `limit + 1` bytes.
+ * `size` is the file's size from fstat. Never throws: a refusal says why, from the one open (`symlink`, `not_regular`, `open_error:<code>`).
+ */
+export function readRegularFileCappedNoFollow(file, limit) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            return { ok: false, reason: "not_regular" };
+        const buf = Buffer.alloc(limit + 1);
+        let n = 0;
+        while (n < buf.length) {
+            const r = fs.readSync(fd, buf, n, buf.length - n, n);
+            if (r === 0)
+                break;
+            n += r;
+        }
+        return { ok: true, buf: buf.subarray(0, Math.min(n, limit)), size: st.size, truncated: n > limit };
+    }
+    catch (e) {
+        const code = e.code ?? "unknown";
+        return { ok: false, reason: code === "ELOOP" ? "symlink" : `open_error:${code}` };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { }
+        }
+    }
+}

package/dist/guard.d.ts

@@ -17,6 +17,8 @@ export declare const MAX_KEEP_BYTES: number;
 export declare class ProtectedGuard {
     private project;
     private baseline;
+    /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
+    private records;
     constructor(project: ResolvedProject);
     /**
      * Take the current files as the baseline. Called right before a batch is woken, so only what changes while it runs is
@@ -30,4 +32,10 @@ export declare class ProtectedGuard {
     private keep;
     /** Compare against the baseline after `running` agents finished; revert unauthorized changes. */
     check(running: ResolvedAgent[]): Violation[];
+    private checkRecords;
+    /**
+     * Make every directory from the records root down to `dir` a real directory. A symlink or file standing in for one is an
+     * unauthorized change: unlink it (never follow it), recreate the directory and report it. False when `dir` is not safe to write into.
+     */
+    private realDirs;
 }

package/dist/guard.js

@@ -1,7 +1,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { mayEditProtected, repoInstructionFiles, sharedContextFiles, sharedIndex } from "./policy.js";
+import { readRegularFileNoFollow } from "./fs-util.js";
+import { mayEditProtected, recordsDir, repoInstructionFiles, sharedContextFiles, sharedIndex } from "./policy.js";
 export const MAX_KEEP_BYTES = 1024 * 1024;
 function safeName(file) {
     return file.replace(/[\\/:]/g, "_").replace(/^_+/, "");
@@ -13,6 +14,8 @@ function safeName(file) {
 export class ProtectedGuard {
     project;
     baseline = new Map();
+    /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
+    records = new Map();
     constructor(project) {
         this.project = project;
         this.rebase();
@@ -24,6 +27,7 @@ export class ProtectedGuard {
     rebase() {
         for (const f of ProtectedGuard.protectedFiles(this.project))
             this.baseline.set(f, read(f));
+        this.records = readTree(recordsDir(this.project));
     }
     static protectedFiles(project) {
         const files = new Set();
@@ -86,8 +90,126 @@ export class ProtectedGuard {
                 violations.push({ file, action: "restored", suspects: running.map((a) => a.name), ...kept });
             }
         }
+        this.checkRecords(running, violations);
         return violations;
     }
+    checkRecords(running, violations) {
+        const root = recordsDir(this.project);
+        // Never write through a symlinked parent of the records tree: skip its protection for this batch.
+        if (isLink(path.dirname(root)) || isLink(path.dirname(path.dirname(root))))
+            return;
+        const now = readTree(root);
+        const lead = running.some((a) => a.name === this.project.lead);
+        const suspects = running.map((a) => a.name);
+        const fixedDirs = new Set();
+        for (const file of new Set([...this.records.keys(), ...now.keys()])) {
+            const before = this.records.get(file) ?? null;
+            const cur = now.get(file) ?? null;
+            if (same(before, cur))
+                continue;
+            if (lead)
+                continue;
+            const kept = this.keep(file, cur);
+            if (before === null) {
+                if (!insideRoot(root, path.dirname(file)))
+                    continue;
+                fs.rmSync(file, { force: true });
+                violations.push({ file, action: "removed", suspects, ...kept });
+            }
+            else {
+                if (!this.realDirs(root, path.dirname(file), fixedDirs, suspects, violations))
+                    continue;
+                fs.rmSync(file, { recursive: true, force: true });
+                fs.writeFileSync(file, before);
+                violations.push({ file, action: "restored", suspects, ...kept });
+            }
+        }
+        if (lead)
+            this.records = now;
+    }
+    /**
+     * Make every directory from the records root down to `dir` a real directory. A symlink or file standing in for one is an
+     * unauthorized change: unlink it (never follow it), recreate the directory and report it. False when `dir` is not safe to write into.
+     */
+    realDirs(root, dir, done, suspects, violations) {
+        const rel = path.relative(root, dir);
+        if (rel.startsWith("..") || path.isAbsolute(rel))
+            return false;
+        let cur = root;
+        for (const part of ["", ...(rel ? rel.split(path.sep) : [])]) {
+            cur = part ? path.join(cur, part) : cur;
+            let st;
+            try {
+                st = fs.lstatSync(cur);
+            }
+            catch { }
+            if (st?.isDirectory())
+                continue;
+            if (st) {
+                fs.rmSync(cur, { force: true });
+                if (!done.has(cur))
+                    violations.push({ file: cur, action: "removed", suspects, ...this.keep(cur, null) });
+                done.add(cur);
+            }
+            fs.mkdirSync(cur, { recursive: true });
+        }
+        return insideRoot(root, dir);
+    }
+}
+function isLink(p) {
+    try {
+        return fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function insideRoot(root, dir) {
+    try {
+        const r = path.relative(fs.realpathSync(root), fs.realpathSync(dir));
+        return !r.startsWith("..") && !path.isAbsolute(r);
+    }
+    catch {
+        return false;
+    }
+}
+/** Regular files under `dir`, recursively; symlinks and special files are not followed or read. */
+function readTree(dir) {
+    const out = new Map();
+    try {
+        if (!fs.lstatSync(dir).isDirectory())
+            return out; // a symlinked root is never walked
+    }
+    catch {
+        return out;
+    }
+    const walk = (d) => {
+        let names;
+        try {
+            names = fs.readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const f = path.join(d, n);
+            try {
+                const st = fs.lstatSync(f);
+                if (st.isDirectory())
+                    walk(f);
+                else if (st.isFile()) {
+                    const buf = readRegularFileNoFollow(f);
+                    if (buf)
+                        out.set(f, buf);
+                }
+            }
+            catch {
+                // vanished while scanning
+            }
+        }
+    };
+    walk(dir);
+    return out;
 }
 function read(file) {
     try {

package/dist/mailbox.js

@@ -7,6 +7,7 @@ import { atomicWrite } from "./fs-util.js";
 import { countFormatRejection, formatRejectionKey, formatRejections, MAX_FORMAT_REJECTIONS } from "./format-rejections.js";
 import { deterministicId, fault, RouteJournal, sourceIdOf } from "./message-store.js";
 import { inboxDir, outboxDir, sharedDir } from "./policy.js";
+import { activeRecordsBytes, RECORD_KINDS, RECORDS_BUDGET } from "./records.js";
 import { must } from "./assert.js";
 export { atomicWrite };
 export const MESSAGE_TYPES = ["task", "reply", "failure", "done", "ask"];
@@ -259,6 +260,11 @@ export function routeOutboxes(project) {
                     reject(`only the lead ("${project.lead}") may send a "done" message.`);
                     continue;
                 }
+                const over = RECORD_KINDS.map((k) => ({ k, n: activeRecordsBytes(project, k) })).filter((x) => x.n > RECORDS_BUDGET);
+                if (over.length) {
+                    reject(`${over.map((x) => `records/${x.k} hold ${x.n} bytes of active entries`).join(" and ")}; the budget is ${RECORDS_BUDGET} bytes (6 KB) per kind. Merge entries, or mark obsolete ones "status: superseded" (or name them in a newer entry's "supersedes"), then send "done" again.`);
+                    continue;
+                }
                 res.done = { from: sender.name, subject, body: parsed.body, file, meta: d };
                 const ds = parseSteps(parsed.body);
                 if (ds.length)

package/dist/memory-tidy.d.ts

@@ -84,6 +84,8 @@ export interface TidyResult {
     status: "tidied" | "skipped" | "failed" | "dry-run";
     /** The archive stamp of a finished tidy. */
     archive?: string;
+    /** Set when the project records were tidied too: their folder (its archive is `<recordsDir>/.archive/<archive>`). */
+    recordsDir?: string;
     problems: string[];
 }
 /** Scratch space of one tidy (snapshot and the invocation's logs); outside every memory dir and every run. */
@@ -96,8 +98,19 @@ export interface RestoreResult {
         rel: string;
         reason: string;
     }[];
+    /** The same for the project records archive of that stamp, when the lead's undo found one. */
+    records?: {
+        restored: string[];
+        skipped: {
+            rel: string;
+            reason: string;
+        }[];
+    };
 }
-/** Move the files of one tidy's archive back to where they were. Nothing that exists now is overwritten. */
+/**
+ * Move the files of one tidy's archive back to where they were. Nothing that exists now is overwritten.
+ * For the lead on the project layer this covers the project records archive of the same stamp too; either archive may be the only one.
+ */
 export declare function restoreMemory(o: {
     project: ResolvedProject;
     agent: string;