agent-lyceum 0.5.0 → 0.7.0

package/dist/memory-tidy.js

@@ -0,0 +1,351 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { realInvoker } from "./adapters/index.js";
+import { atomicWrite } from "./fs-util.js";
+import { ensureProjectDirs } from "./mailbox.js";
+import { memoryDirs } from "./policy.js";
+import { buildTidyPrompts, MEMORY_INDEX_LIMIT } from "./prompt.js";
+import { git, isGitRepo } from "./worktree.js";
+export const ARCHIVE_DIR = ".archive";
+export const TIDY_STATE_FILE = ".tidy-state.json";
+export const TIDY_REPORT_FILE = "tidy-report.md";
+export const STAMP_RE = /^\d{8}T\d{6}Z$/;
+/** `20261008T031500Z`: UTC, sortable, safe in a file name. */
+export const tidyStamp = (d = new Date()) => d.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+/** The memory directories to tidy. Without `agent`, every agent that has a directory for the layer; with it, that agent or an error. */
+export function targetsFor(project, opts) {
+    const pick = (name) => {
+        const dir = project.agents[name]?.memory[opts.layer];
+        return dir ? { agent: name, layer: opts.layer, dir } : undefined;
+    };
+    if (opts.agent) {
+        if (!project.agents[opts.agent])
+            throw new Error(`No agent "${opts.agent}" in project ${project.name}. Agents: ${Object.keys(project.agents).join(", ")}.`);
+        const t = pick(opts.agent);
+        if (!t)
+            throw new Error(`Agent "${opts.agent}" has no ${opts.layer} memory directory.`);
+        return [t];
+    }
+    return Object.keys(project.agents).flatMap((n) => pick(n) ?? []);
+}
+function walk(dir, base, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            walk(full, base, out);
+        else if (e.isFile()) {
+            const rel = path.relative(base, full).split(path.sep).join("/");
+            if (rel === TIDY_STATE_FILE)
+                continue;
+            const st = fs.statSync(full);
+            out.push({ rel, bytes: st.size, mtime: st.mtime.toISOString() });
+        }
+    }
+}
+/** Every file under `dir` (the archive included, the state file not), `/`-separated and sorted. */
+export function listMemoryFiles(dir) {
+    const out = [];
+    walk(dir, dir, out);
+    return out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+}
+/** Size and age of the live files (the archive is not counted). */
+export function memoryStats(dir) {
+    const live = listMemoryFiles(dir).filter((f) => !f.rel.startsWith(`${ARCHIVE_DIR}/`));
+    const times = live.map((f) => f.mtime).sort();
+    return {
+        files: live.length,
+        bytes: live.reduce((n, f) => n + f.bytes, 0),
+        indexBytes: live.find((f) => f.rel === "MEMORY.md")?.bytes ?? 0,
+        oldest: times[0],
+        newest: times.at(-1),
+    };
+}
+/** Content hash of every file (the archive included), to tell whether a directory changed. */
+export function fingerprint(dir) {
+    const out = {};
+    for (const f of listMemoryFiles(dir))
+        out[f.rel] = crypto.createHash("sha256").update(fs.readFileSync(path.join(dir, f.rel))).digest("hex");
+    return out;
+}
+const slot = (into, i) => path.join(into, String(i));
+/** Copy each directory aside (a directory that does not exist is remembered as absent). */
+export function snapshotDirs(dirs, into) {
+    fs.rmSync(into, { recursive: true, force: true });
+    fs.mkdirSync(into, { recursive: true });
+    dirs.forEach((d, i) => {
+        if (fs.existsSync(d))
+            fs.cpSync(d, slot(into, i), { recursive: true });
+    });
+}
+/** Put each directory back as `snapshotDirs` saw it, removing whatever was added since. */
+export function restoreDirs(dirs, from) {
+    dirs.forEach((d, i) => {
+        fs.rmSync(d, { recursive: true, force: true });
+        if (fs.existsSync(slot(from, i)))
+            fs.cpSync(slot(from, i), d, { recursive: true });
+    });
+}
+/**
+ * Nothing may disappear: every file that existed before is still in place, or archived under the same relative
+ * path in this tidy's archive folder. Earlier archives must stay as they were; MEMORY.md is never archived.
+ */
+export function verifyConservation(before, dir, stamp) {
+    const problems = [];
+    for (const rel of before) {
+        const here = fs.existsSync(path.join(dir, rel));
+        if (here)
+            continue;
+        const inArchive = !rel.startsWith(`${ARCHIVE_DIR}/`) && rel !== "MEMORY.md" && fs.existsSync(path.join(dir, ARCHIVE_DIR, stamp, rel));
+        if (!inArchive)
+            problems.push(rel === "MEMORY.md" ? `MEMORY.md is missing (the index must stay in place)` : `${rel} is gone: it is neither in place nor under ${ARCHIVE_DIR}/${stamp}/`);
+    }
+    return problems;
+}
+export function readTidyState(dir) {
+    try {
+        const j = JSON.parse(fs.readFileSync(path.join(dir, TIDY_STATE_FILE), "utf8"));
+        return j && typeof j === "object" && typeof j.at === "string" ? j : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeTidyState(dir, st) {
+    atomicWrite(path.join(dir, TIDY_STATE_FILE), JSON.stringify(st, null, 2));
+}
+const LOG_LINES = 50;
+const STAT_LINES = 40;
+function tryGit(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return undefined;
+    }
+}
+const lines = (s) => (s ? s.split("\n").filter(Boolean) : []);
+export function projectChanges(repoDir, since) {
+    if (!fs.existsSync(repoDir) || !isGitRepo(repoDir))
+        return { log: [], stat: [], note: "the project directory is not a git repository" };
+    const head = tryGit(repoDir, ["rev-parse", "HEAD"]);
+    if (!head)
+        return { log: [], stat: [], note: "the repository has no commits yet" };
+    if (!since)
+        return { head, log: [], stat: [], note: "first tidy: there is no earlier baseline, only the path check applies" };
+    if (since === head)
+        return { head, since, log: [], stat: [], note: "no commits since the last tidy" };
+    if (tryGit(repoDir, ["cat-file", "-t", `${since}^{commit}`]) !== "commit")
+        return { head, since, log: [], stat: [], note: "the baseline commit of the last tidy no longer exists in this repository (history was rewritten?)" };
+    const log = lines(tryGit(repoDir, ["log", "--oneline", "--no-decorate", `${since}..${head}`]));
+    const stat = lines(tryGit(repoDir, ["diff", "--stat", since, head]));
+    return {
+        head,
+        since,
+        log: log.length > LOG_LINES ? [...log.slice(0, LOG_LINES), `… and ${log.length - LOG_LINES} more commits`] : log,
+        stat: stat.length > STAT_LINES ? [...stat.slice(0, STAT_LINES - 1), stat.at(-1) ?? ""] : stat,
+    };
+}
+const PATH_TOKEN = /`([^`\n]+)`/g;
+function looksLikePath(t) {
+    if (!t.includes("/") || /\s/.test(t) || t.includes("://"))
+        return false;
+    if (/^-|[*?{}<>$|;&=]/.test(t))
+        return false;
+    return true;
+}
+/** Backticked paths in the live Markdown files of `dir` that do not exist. Relative ones are looked up in `repoDir` (skipped without it). */
+export function findMissingPaths(dir, repoDir) {
+    const seen = new Set();
+    const out = [];
+    for (const f of listMemoryFiles(dir)) {
+        if (f.rel.startsWith(`${ARCHIVE_DIR}/`) || !f.rel.endsWith(".md"))
+            continue;
+        const text = fs.readFileSync(path.join(dir, f.rel), "utf8");
+        for (const m of text.matchAll(PATH_TOKEN)) {
+            const tok = (m[1] ?? "").trim();
+            if (!looksLikePath(tok))
+                continue;
+            const abs = tok.startsWith("~/") ? path.join(os.homedir(), tok.slice(2)) : path.isAbsolute(tok) ? tok : repoDir ? path.join(repoDir, tok) : undefined;
+            if (!abs || fs.existsSync(abs))
+                continue;
+            const key = `${f.rel}\0${tok}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ file: f.rel, path: tok });
+        }
+    }
+    return out;
+}
+/** Scratch space of one tidy (snapshot and the invocation's logs); outside every memory dir and every run. */
+export const tidyWorkDir = (project, stamp, agent) => path.join(project.paths.root, "tidy-work", stamp, agent);
+const kb = (n) => (n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KiB`);
+function describeTarget(t, project, say) {
+    const s = memoryStats(t.dir);
+    say(`${t.agent} (${t.layer}): ${s.files} file(s), ${kb(s.bytes)}, MEMORY.md ${kb(s.indexBytes)}${s.oldest ? `, modified ${s.oldest.slice(0, 10)} … ${s.newest?.slice(0, 10)}` : ""}`);
+    if (t.layer === "project") {
+        const c = projectChanges(project.dir, readTidyState(t.dir)?.head);
+        say(`  project changes: ${c.note ?? `${c.log.length} commit(s) since ${c.since?.slice(0, 8)}`}`);
+    }
+    for (const m of findMissingPaths(t.dir, t.layer === "project" ? project.dir : undefined))
+        say(`  missing path: ${m.path} (in ${m.file})`);
+}
+async function tidyOne(o, t, stamp) {
+    const { project } = o;
+    const say = o.say ?? ((s) => console.log(s));
+    const base = { agent: t.agent, layer: t.layer, dir: t.dir };
+    const agent = project.agents[t.agent];
+    const live = listMemoryFiles(t.dir).filter((f) => !f.rel.startsWith(`${ARCHIVE_DIR}/`));
+    if (live.length === 0)
+        return { ...base, status: "skipped", problems: ["no memory files: nothing to tidy"] };
+    const dirs = memoryDirs(agent);
+    const others = dirs.filter((d) => d !== t.dir);
+    const before = listMemoryFiles(t.dir).map((f) => f.rel);
+    const othersBefore = others.map((d) => fingerprint(d));
+    const archiveDir = path.join(t.dir, ARCHIVE_DIR, stamp);
+    const workDir = tidyWorkDir(project, stamp, t.agent);
+    const snapshot = path.join(workDir, "snapshot");
+    const state = readTidyState(t.dir);
+    const changes = t.layer === "project" ? projectChanges(project.dir, state?.head) : undefined;
+    const missing = findMissingPaths(t.dir, t.layer === "project" ? project.dir : undefined);
+    const index = fs.existsSync(path.join(t.dir, "MEMORY.md")) ? fs.readFileSync(path.join(t.dir, "MEMORY.md"), "utf8") : "";
+    const prompts = buildTidyPrompts(agent, { layer: t.layer, dir: t.dir, archiveDir, files: live, index, changes, missing });
+    ensureProjectDirs(project);
+    snapshotDirs(dirs, snapshot);
+    const fail = (problems) => {
+        restoreDirs(dirs, snapshot);
+        fs.rmSync(snapshot, { recursive: true, force: true });
+        return { ...base, status: "failed", problems };
+    };
+    say(`tidying ${t.layer} memory of ${t.agent} (${live.length} file(s)) …`);
+    const invoke = o.invoker ?? realInvoker;
+    const result = await invoke({
+        project,
+        agent,
+        workDir,
+        systemPrompt: prompts.systemPrompt,
+        userPrompt: prompts.userPrompt,
+        timeoutSec: project.dispatcher.wake_timeout_sec,
+        signal: o.signal,
+        logDir: path.join(workDir, "log"),
+    }).catch((e) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: e.message }));
+    if (!result.ok)
+        return fail([`the wake-up failed: ${result.error ?? "unknown error"}`]);
+    const problems = [];
+    others.forEach((d, i) => {
+        if (JSON.stringify(fingerprint(d)) !== JSON.stringify(othersBefore[i]))
+            problems.push(`the agent changed ${d}, which is not the ${t.layer} memory being tidied`);
+    });
+    problems.push(...verifyConservation(before, t.dir, stamp));
+    const reportFile = path.join(archiveDir, TIDY_REPORT_FILE);
+    if (!fs.existsSync(reportFile) || fs.readFileSync(reportFile, "utf8").trim() === "")
+        problems.push(`${ARCHIVE_DIR}/${stamp}/${TIDY_REPORT_FILE} is missing or empty`);
+    if (problems.length)
+        return fail(problems);
+    fs.rmSync(snapshot, { recursive: true, force: true });
+    writeTidyState(t.dir, { ...(changes?.head ? { head: changes.head } : {}), at: (o.now?.() ?? new Date()).toISOString(), archive: stamp });
+    return { ...base, status: "tidied", archive: stamp, problems: [] };
+}
+/** Tidy the memory of the chosen agents, one after another. Only ever called by a person (`agent-lyceum memory tidy`). */
+export async function tidyMemory(o) {
+    const say = o.say ?? ((s) => console.log(s));
+    const targets = targetsFor(o.project, { layer: o.layer, agent: o.agent });
+    const results = [];
+    for (const t of targets) {
+        if (o.dryRun) {
+            describeTarget(t, o.project, say);
+            results.push({ agent: t.agent, layer: t.layer, dir: t.dir, status: "dry-run", problems: [] });
+            continue;
+        }
+        const r = await tidyOne(o, t, tidyStamp(o.now?.()));
+        results.push(r);
+        if (o.signal?.aborted)
+            break;
+    }
+    return results;
+}
+function titleOf(file, rel) {
+    const text = fs.readFileSync(file, "utf8");
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    const name = fm ? /^name:\s*(.+)$/m.exec(fm[1] ?? "")?.[1]?.trim() : undefined;
+    if (name)
+        return name;
+    const h = /^#\s+(.+)$/m.exec(text)?.[1]?.trim();
+    return h || path.basename(rel, path.extname(rel));
+}
+function pruneEmpty(dir, stop) {
+    for (let d = dir; d !== stop && d.startsWith(stop + path.sep); d = path.dirname(d)) {
+        if (fs.readdirSync(d).length)
+            break;
+        fs.rmdirSync(d);
+    }
+}
+/** Move the files of one tidy's archive back to where they were. Nothing that exists now is overwritten. */
+export function restoreMemory(o) {
+    if (!STAMP_RE.test(o.stamp))
+        throw new Error(`"${o.stamp}" is not an archive stamp (expected something like 20261008T031500Z).`);
+    const [t] = targetsFor(o.project, { layer: o.layer, agent: o.agent });
+    const archive = path.join(t.dir, ARCHIVE_DIR, o.stamp);
+    if (!fs.existsSync(archive))
+        throw new Error(`No archive ${o.stamp} for ${o.agent} (${o.layer}). Archives: ${listArchives(t.dir).join(", ") || "(none)"}.`);
+    const restored = [];
+    const skipped = [];
+    const inArchive = listMemoryFiles(archive).filter((f) => f.rel !== TIDY_REPORT_FILE);
+    for (const f of inArchive) {
+        const from = path.join(archive, f.rel);
+        const to = path.join(t.dir, f.rel);
+        if (fs.existsSync(to)) {
+            skipped.push({ rel: f.rel, reason: "a file with this name exists now; it was not overwritten" });
+            continue;
+        }
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        fs.renameSync(from, to);
+        pruneEmpty(path.dirname(from), archive);
+        restored.push(f.rel);
+    }
+    const indexFile = path.join(t.dir, "MEMORY.md");
+    const index = fs.existsSync(indexFile) ? fs.readFileSync(indexFile, "utf8") : "";
+    const add = restored.filter((rel) => rel.endsWith(".md") && !index.includes(rel)).map((rel) => `- [${titleOf(path.join(t.dir, rel), rel)}](${rel}) — restored from tidy ${o.stamp}`);
+    if (add.length)
+        atomicWrite(indexFile, `${index.replace(/\n*$/, index ? "\n" : "")}${add.join("\n")}\n`);
+    return { restored, skipped };
+}
+/** The stamps of the archives in a memory directory, oldest first. */
+export function listArchives(dir) {
+    try {
+        return fs.readdirSync(path.join(dir, ARCHIVE_DIR)).filter((n) => STAMP_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export const ADVICE_COMMITS = 50;
+/** Hints only: project memory whose index is larger than what an agent is shown, or whose baseline is far behind. Never acts. */
+export function tidyAdvice(project) {
+    const out = [];
+    for (const t of targetsFor(project, { layer: "project" })) {
+        if (!fs.existsSync(t.dir))
+            continue;
+        const s = memoryStats(t.dir);
+        if (s.indexBytes > MEMORY_INDEX_LIMIT) {
+            out.push({ agent: t.agent, reason: `MEMORY.md is ${s.indexBytes} bytes, more than the ${MEMORY_INDEX_LIMIT} an agent is shown` });
+            continue;
+        }
+        const since = readTidyState(t.dir)?.head;
+        if (!since || !fs.existsSync(project.dir) || !isGitRepo(project.dir))
+            continue;
+        const n = Number(tryGit(project.dir, ["rev-list", "--count", `${since}..HEAD`]));
+        if (Number.isFinite(n) && n >= ADVICE_COMMITS)
+            out.push({ agent: t.agent, reason: `${n} commits since the last tidy` });
+    }
+    return out;
+}

package/dist/policy.js

@@ -49,9 +49,10 @@ export function repoDirFor(project, agent) {
     return project.workspaces?.[agent]?.dir ?? project.dir;
 }
 export function writePolicy(project, agent) {
-    const isLead = agent.name === project.lead;
+    const isLead = agent.name === project.lead && !project.solo;
     const ws = project.workspaces?.[agent.name];
-    const allowDirs = [...memoryDirs(agent), outboxDir(project, agent.name), ...(ws ? [ws.gitDir] : [])];
+    // A `call` has no mailboxes at all; a solo member of a run keeps its outbox to send `done`.
+    const allowDirs = [...memoryDirs(agent), ...(project.solo === "call" ? [] : [outboxDir(project, agent.name)]), ...(ws ? [ws.gitDir] : [])];
     const allowFiles = [];
     if (isLead)
         allowFiles.push(commonFile(project));

package/dist/prompt.d.ts

@@ -1,11 +1,35 @@
 import type { ResolvedAgent, ResolvedProject } from "./config.js";
 import type { Message } from "./mailbox.js";
+import type { Layer, MemoryFile, MissingPath, ProjectChanges } from "./memory-tidy.js";
 export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_LIMIT: number;
 export declare const LEAD_BATCH_LIMIT = 5;
 export declare function readPersona(agent: ResolvedAgent): string;
+/** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
+export declare function buildSoloSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
+/** The prompt of a `call`: the memory indexes the agent is used to, then the task. */
+export declare function buildCallUserPrompt(agent: ResolvedAgent, task: string): string;
 /** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
 export declare function buildSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
 /** Messages one wake-up handles: the oldest one, or for the lead a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so it decides once on all of it. */
 export declare function pickMessages(project: ResolvedProject, agent: ResolvedAgent, queue: Message[]): Message[];
 export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number): string;
+export interface TidyContext {
+    layer: Layer;
+    /** The memory directory being tidied. */
+    dir: string;
+    /** Absolute path of this tidy's archive folder (the agent creates it). */
+    archiveDir: string;
+    /** Live files only (the archive is not listed). */
+    files: MemoryFile[];
+    /** MEMORY.md text ("" when there is none). */
+    index: string;
+    /** What changed in the project since the last tidy (project layer only). */
+    changes?: ProjectChanges;
+    missing: MissingPath[];
+}
+/** The prompts of a memory-tidy wake-up: a maintenance job, not a task, so it has none of the mail protocol. */
+export declare function buildTidyPrompts(agent: ResolvedAgent, ctx: TidyContext): {
+    systemPrompt: string;
+    userPrompt: string;
+};

package/dist/prompt.js

@@ -22,8 +22,46 @@ function readCapped(file, limit) {
 export function readPersona(agent) {
     return fs.readFileSync(agent.agentMd, "utf8").trim();
 }
+/** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
+export function buildSoloSystemPrompt(project, agent) {
+    const isCall = project.solo === "call";
+    const lines = [readPersona(agent), "", "---", "", "# Solo protocol (injected by agent-lyceum)", ""];
+    lines.push(`You are **${agent.name}**, working alone: there is no team, no lead and nobody to mail, and you cannot ask the user questions. You work in \`${repoDirFor(project, agent.name)}\`.`, isCall
+        ? "Do the task you are given. Your final reply text is printed to the user as your answer, so end with the answer or a short report of what you did; nothing else is delivered."
+        : "");
+    if (!isCall) {
+        lines.push("## Finishing", `When the job is finished, create a Markdown file (any name ending in \`.md\`) directly inside \`${outboxDir(project, agent.name)}\` with this exact shape:`, "", "```", "---", "type: done", "subject: <short subject>", "outcome: completed|partial|blocked|failed", "---", "", "## Result", "## Files", "## Verification", "## Not done", "```", "", "That ends the run. `## Result` is the actual deliverable or conclusion (not just \"done\"), `## Files` the paths you created or changed, `## Verification` what you ran or checked and what it showed, `## Not done` anything skipped or unverified (or `None`). Only `completed` means success and it needs all four headings; if work remains or is blocked say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A summary in your reply text is never delivered: without a `done` mail the run ends as idle with no report.");
+    }
+    lines.push("", "## Memory");
+    const mems = memoryDirs(agent);
+    if (mems.length === 0)
+        lines.push("You have no long-term memory directory.");
+    for (const m of mems)
+        lines.push(`- ${memoryLabel(agent, m)}: \`${m}\``);
+    if (mems.length) {
+        lines.push("Keep a `MEMORY.md` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt on every wake-up; you can write only inside these directories.", "Use memory only for durable lessons that stay true across tasks; never record task-specific details there.");
+    }
+    lines.push("", "## Rules", "- Never edit any `AGENT.md`, `COMMON.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`.", "- Never touch another agent's memory, inbox or outbox, or the configuration files of agent-lyceum.");
+    return lines.join("\n");
+}
+/** The prompt of a `call`: the memory indexes the agent is used to, then the task. */
+export function buildCallUserPrompt(agent, task) {
+    const parts = [];
+    for (const dir of memoryDirs(agent)) {
+        const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
+        parts.push(`# Your ${memoryLabel(agent, dir).split(" ")[0]} memory index (${dir}/MEMORY.md)`);
+        if (!idx)
+            parts.push("(no MEMORY.md yet — create one when you have something worth keeping)", "");
+        else
+            parts.push(idx.text.trim(), ...(idx.truncated ? [`[index truncated at ${MEMORY_INDEX_LIMIT} bytes — trim it]`] : []), "");
+    }
+    parts.push("# Task", task.trim());
+    return parts.join("\n");
+}
 /** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
 export function buildSystemPrompt(project, agent) {
+    if (project.solo)
+        return buildSoloSystemPrompt(project, agent);
     const outbox = outboxDir(project, agent.name);
     const mates = Object.keys(project.agents).filter((n) => n !== agent.name);
     const recipients = agent.canMessage === "all" ? mates : agent.canMessage.filter((n) => project.agents[n] && n !== agent.name);
@@ -34,13 +72,31 @@ export function buildSystemPrompt(project, agent) {
         ? [
             `That directory is your own isolated git worktree (branch \`${project.workspaces?.[agent.name]?.branch}\`): teammates cannot see your changes while you work, and you cannot see theirs. Do not commit, push, switch branches or touch any other checkout; the dispatcher collects your changes from this directory after you finish.`,
         ]
-        : []), `The team lead is **${project.lead}**${isLead ? " (that is you)" : ""}. Teammates: ${mates.join(", ") || "(none)"}.`, "", "## Sending mail", "You cannot talk to teammates directly. Mail you receive is shown in your prompt. To send mail, create a Markdown file", `(any name ending in \`.md\`) directly inside \`${outbox}\` with this exact shape:`, "", "```", "---", "to: <agent-name>", "type: reply        # task | reply" + (isLead ? " | done" : ""), "subject: <short subject>", "reply_to: <message id>   # optional", "---", "", "<body>", "```", "", `You may send to: ${recipients.join(", ") || "(nobody)"}.`, isLead
+        : []), `The team lead is **${project.lead}**${isLead ? " (that is you)" : ""}. Teammates: ${mates.join(", ") || "(none)"}.`, "", "## Sending mail", "You cannot talk to teammates directly. Mail you receive is shown in your prompt. To send mail, create a Markdown file", `(any name ending in \`.md\`) directly inside \`${outbox}\` with this exact shape:`, "", "```", "---", "to: <agent-name>", `type: reply        # task | reply${agent.canAskUser ? " | ask" : ""}${isLead ? " | done" : ""}`, "subject: <short subject>", "reply_to: <message id>   # optional", "---", "", "<body>", "```", "", `You may send to: ${recipients.join(", ") || "(nobody)"}.`, isLead
         ? `When the whole job is finished, send a message with \`type: done\` (no \`to\` needed). That ends the run. A summary in your reply text is never delivered and does not end the run: after the last teammate reply is verified you MUST send \`done\` (or a \`task\` for the remaining work), or the run stops as "idle" with no final report.`
         : `Report results to the lead by mail; the lead decides what happens next.`, isLead
         ? "Each wake-up handles one message, except that several `reply`/`failure` messages waiting together are handed to you in one wake-up: weigh them together, then decide the next step once."
         : "Each wake-up handles one message. Do the work it asks, then send the replies that are needed, then stop.", "", "## Message format", "The body of every `task` and `reply` must contain these `##` headings, exactly as written (write `None` under a heading if there is nothing to say).", "Mail missing a heading is still delivered, but is flagged to the recipient.", "", `- \`task\`: ${REQUIRED_SECTIONS.task.map((h) => `\`## ${h}\``).join(", ")} (Upstream = id of the mail this task derives from, or \`None\`).`, `- \`reply\`: ${REQUIRED_SECTIONS.reply.map((h) => `\`## ${h}\``).join(", ")}.`, isLead
         ? "- `done`: your final report to the user (shown when the run ends, saved as `result.md`). Its frontmatter must contain `outcome: completed|partial|blocked|failed`, and the body the headings `## Result` (the actual deliverable or conclusion, not just \"done\"), `## Files` (paths created or changed), `## Verification` (what you ran or checked, and what it showed) and `## Not done` (anything skipped or unverified, or `None`). Only `completed` means success, and it needs all four headings and every checklist step ticked; if work remains or is blocked, say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A `done` that breaks this is sent back to you and does not end the run."
-        : "- `done` has no required headings.", ...(isLead
+        : "- `done` has no required headings.", ...(agent.canAskUser
+        ? [
+            "",
+            "## Asking the user",
+            "You may ask the human user with `type: ask` (no `to` needed). The run then pauses until they answer, so ask only when the answer changes what you do next and you cannot work it out from the code, the memory or the task. Ask everything you need in ONE batch (at most 10 questions); prefer questions with `<options>` and a `<suggested>` value (with a `reason`) so the user can answer quickly. The body is exactly this:",
+            "",
+            "```",
+            "<ask>",
+            '  <question id="q1">',
+            "    <text>Session or JWT for login?</text>",
+            "    <options><option>session</option><option>jwt</option></options>",
+            '    <suggested reason="existing code already uses cookies">session</suggested>',
+            "  </question>",
+            "</ask>",
+            "```",
+            "",
+            "The answers come back to you as a `reply` mail containing an `<answers>` block. A user answer that starts with `other:` is free text. Do not ask what you could decide yourself, and do not ask again for something already answered.",
+        ]
+        : []), ...(isLead
         ? [
             "",
             "## Progress tracking (optional, shown in `agent-lyceum status`)",
@@ -123,3 +179,58 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1) {
     }
     return parts.join("\n");
 }
+/** The prompts of a memory-tidy wake-up: a maintenance job, not a task, so it has none of the mail protocol. */
+export function buildTidyPrompts(agent, ctx) {
+    const systemPrompt = [
+        readPersona(agent),
+        "",
+        "---",
+        "",
+        "# Memory tidy (injected by agent-lyceum)",
+        "",
+        `You are **${agent.name}**. This wake-up is a maintenance job, not a task: there is no mail to send or read, and nothing to do in the repository. Your only job is to tidy your own ${ctx.layer} memory so it stays small, accurate and useful.`,
+        "",
+        "## What you may touch",
+        `Only files inside \`${ctx.dir}\`. Everything else is read-only. Do not touch your other memory directories, \`${ctx.dir}/.tidy-state.json\` or the archive folders of earlier tidies.`,
+        "",
+        "## What to do",
+        "- Merge entries that say the same thing; keep one file with the combined, current content.",
+        "- Rewrite entries that are stale (see the project changes and the missing paths below); correct them if you can tell what is true now, otherwise keep them and say so in the report.",
+        "- Keep `MEMORY.md` as the index: one line per entry, each pointing at an existing file, and nothing for files that were archived.",
+        "- **When unsure, keep it.** Prefer leaving an entry alone over losing information.",
+        "",
+        "## Never delete",
+        `To retire a file, move it into the archive folder, keeping its relative path (\`${ctx.dir}/x/y.md\` goes to \`${ctx.archiveDir}/x/y.md\`). Never delete a file. \`MEMORY.md\` itself is never archived. A file whose content you merged into another one is archived too.`,
+        "",
+        "## Before you finish",
+        `Write \`${ctx.archiveDir}/tidy-report.md\` — even when you changed nothing — with these headings: \`## Merged\` (what was combined into what), \`## Archived\` (each archived file and why), \`## Unsure\` (things you kept but doubt). Write \`None\` under a heading with nothing to say. The tidy is rolled back if the report is missing or any file went missing.`,
+    ].join("\n");
+    const parts = [
+        `Archive directory: ${ctx.archiveDir}`,
+        `Layer: ${ctx.layer}${ctx.layer === "global" ? " (shared by every project; do not judge entries by one project's code)" : ""}`,
+        `Memory directory: ${ctx.dir}`,
+        "",
+        "# Files",
+        ...(ctx.files.length ? ctx.files.map((f) => `${f.rel}  ${f.bytes} B  modified ${f.mtime.slice(0, 10)}`) : ["(none)"]),
+        "",
+        `# MEMORY.md (${ctx.dir}/MEMORY.md)`,
+        ctx.index.trim() ? ctx.index.trim() : "(no MEMORY.md)",
+    ];
+    if (ctx.layer === "project") {
+        const c = ctx.changes;
+        parts.push("", "# Changes in the project since the last tidy");
+        if (!c)
+            parts.push("(not available)");
+        else {
+            if (c.note)
+                parts.push(c.note);
+            if (c.log.length)
+                parts.push("", "Commits:", ...c.log);
+            if (c.stat.length)
+                parts.push("", "Files changed:", ...c.stat);
+        }
+    }
+    parts.push("", "# Paths named in the memory that no longer exist");
+    parts.push(...(ctx.missing.length ? ctx.missing.map((m) => `- \`${m.path}\` (mentioned in ${m.file})`) : ["(none found)"]));
+    return { systemPrompt, userPrompt: parts.join("\n") };
+}

package/dist/run-outcome.js

@@ -16,6 +16,8 @@ export function endOutcome(endReason, done) {
             return { outcome: done?.outcome ?? "partial", note: done?.note };
         case "lead_failed":
             return { outcome: "failed", note: "The lead's wake-up failed." };
+        case "waiting":
+            return { outcome: "waiting", note: "Waiting for your answers. Fill in ask-reply.md or run `agent-lyceum answer <run-id>`, then continue with `agent-lyceum resume`." };
         case "cancelled":
             return { outcome: "cancelled", note: "Cancelled before the lead finished. Unread mail was kept; continue with `agent-lyceum resume`." };
         case "idle":

package/dist/run-session.d.ts

@@ -8,6 +8,8 @@ export type { ActiveWake, EndReason, RunState, SentTopic, WakeRecord, WakeTopic
 export declare const RESULT_FILE = "result.md";
 /** How many times a non-conforming `done` goes back to the lead before it is accepted as `partial`. */
 export declare const MAX_DONE_REJECTIONS = 2;
+/** How many times a malformed `ask` goes back to its sender before the lead is told instead. */
+export declare const MAX_ASK_REJECTIONS = 2;
 export interface RunSummary {
     runId: string;
     runDir: string;
@@ -21,9 +23,13 @@ export interface RunSummary {
         subject: string;
         body: string;
     };
+    /** Set when the run waits for the user: the file with the questions. */
+    askReplyPath?: string;
 }
 export interface RunOptions {
     project: ResolvedProject;
+    /** Run only this member of the project, alone (`run --agent`). A resumed run uses the one recorded in its state. */
+    soloAgent?: string;
     /** The task for a new run; omit when resuming. */
     task?: PreparedTask;
     /** Continue this earlier run (same run dir, sessions and counters) instead of starting a new one. */
@@ -63,6 +69,8 @@ export declare class RunSession {
     /** The attempt that produced each batch member's output; committed together with its claim. */
     private readonly attempts;
     constructor(opts: RunOptions);
+    /** A waiting run only continues once every unanswered question has a valid answer. */
+    private static assertAnswered;
     private saveState;
     private journal;
     private note;
@@ -76,6 +84,10 @@ export declare class RunSession {
     private integrateMember;
     /** After a batch (or, on resume, before the first one): revert guarded edits, route mail, detect done / lead failure. */
     private settle;
+    /** The user answered: send each asker its answers as a `reply`, then mark them delivered. Safe to repeat after a crash. */
+    private deliverAnswers;
+    /** Store the questions of this pass's valid `ask` mails; malformed ones go back to their sender. Returns true when the run should now wait. */
+    private handleAsks;
     /** On resume: sort out what the interrupted process left behind before anything is woken. */
     private recover;
     run(): Promise<RunSummary>;