agent-lyceum 0.5.0 → 0.7.0

package/dist/cli.js

@@ -3,7 +3,9 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { Command } from "commander";
-import { ConfigError, findProjectForCwd, flattenResolved, listProjects, resolveProject, resolveProjectWithSources } from "./config.js";
+import { ConfigError, findProjectForCwd, flattenResolved, listProjects, loadGlobal, resolveProject, resolveProjectWithSources } from "./config.js";
+import { openInEditor, prepareAnswers } from "./ask-answer.js";
+import { restoreMemory, tidyMemory, tidyStamp } from "./memory-tidy.js";
 import { RESULT_FILE, runTeam } from "./dispatcher.js";
 import { executeRunCleanup, planRunCleanup } from "./run-cleanup.js";
 import { diagnoseProject, formatDoctor, preflightRuntimes } from "./doctor.js";
@@ -14,8 +16,10 @@ import { absPath, assertName, projectPaths, resolveHome } from "./paths.js";
 import { addProject, initHome, removeProject } from "./scaffold.js";
 import { buildStatusReport, buildTaskListReport, formatMonitor, formatRunDetail, formatStatusWithLog, formatTaskList, latestUnfinishedRun, runIsAlive } from "./status.js";
 import { prepareTask, readTaskFile } from "./task.js";
+import { callAgent, callProject, callsDir, resolveCallAgent } from "./call.js";
 import { formatEnforcement, validateProject } from "./validate.js";
 import { must } from "./assert.js";
+import { onlyAgent, soloProject } from "./solo.js";
 const program = new Command();
 program
     .name("agent-lyceum")
@@ -177,7 +181,7 @@ function cancelOnSignals() {
         },
     };
 }
-function reportRun(summary, runDir) {
+function printRun(summary, runDir) {
     console.log(`\nRun ${summary.runId} ended: ${summary.endReason}, outcome: ${summary.outcome}, after ${summary.rounds} round(s). Logs: ${path.join(runDir, "log.jsonl")}`);
     if (summary.outcomeNote)
         console.log(`Note: ${summary.outcomeNote}`);
@@ -187,13 +191,73 @@ function reportRun(summary, runDir) {
         console.log(`\nLead's final message — ${summary.doneMessage.subject}\n\n${summary.doneMessage.body}`);
         console.log(`\nResult saved to: ${path.join(runDir, RESULT_FILE)}`);
     }
+}
+function reportRun(summary, runDir) {
+    printRun(summary, runDir);
     process.exit(exitCodeForOutcome(summary.outcome));
 }
+/** Take the lock and continue a run; the lock is released when it stops (also when it stops because it waits for answers). */
+async function continueRun(pr, dir, runId) {
+    const lease = takeLock(pr, runId);
+    const cancel = cancelOnSignals();
+    try {
+        console.log(`Project ${pr.name} — repo ${pr.dir}`);
+        const state = loadRunState(dir);
+        console.log(`Resuming run ${state.run_id} (${state.end_reason ?? "interrupted"}) at round ${state.rounds}/${pr.dispatcher.max_rounds}: ${state.task_summary}`);
+        // Read the state again under the lock: another process may have changed it while we were checking.
+        return await runTeam({ project: pr, resume: state, runDir: dir, signal: cancel.signal });
+    }
+    finally {
+        cancel.dispose();
+        lease.release();
+    }
+}
+const interactive = () => !!process.stdin.isTTY && !!process.stdout.isTTY;
+function printWaiting(pr, runId, file, problems) {
+    console.log(`\nRun ${runId} is waiting for your answers.\n  File: ${file}`);
+    for (const p of problems)
+        console.log(`  - ${p}`);
+    console.log(`Answer with: agent-lyceum answer ${runId} -p ${pr.name}   (or edit the file, then: agent-lyceum resume ${runId} -p ${pr.name})`);
+}
+/**
+ * Keep going while the run stops to ask and the questions can be settled right now: by --assume-defaults, or (in a terminal)
+ * by opening the editor. Otherwise print where to answer and exit 3.
+ */
+async function driveRun(pr, runDir, first, assumeDefaults) {
+    let summary = first;
+    while (summary.outcome === "waiting") {
+        let prep = prepareAnswers(runDir, { assumeDefaults });
+        while (!prep.complete && interactive()) {
+            console.log(`\nRun ${summary.runId} needs your answers (${prep.path}).`);
+            openInEditor(prep.path);
+            prep = prepareAnswers(runDir, {});
+            if (prep.complete)
+                break;
+            console.log("Some answers are missing or invalid:");
+            for (const p of prep.problems)
+                console.log(`  - ${p}`);
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            const again = (await rl.question("Edit again? [Y/n] ")).trim().toLowerCase();
+            rl.close();
+            if (again === "n" || again === "no")
+                break;
+        }
+        if (!prep.complete) {
+            printRun(summary, runDir);
+            printWaiting(pr, summary.runId, prep.path, prep.problems);
+            process.exit(3);
+        }
+        summary = await continueRun(pr, runDir, summary.runId);
+    }
+    return reportRun(summary, runDir);
+}
 program
     .command("run [task]")
-    .description('Start the dispatcher: give the task to the lead. Use "<task>" or --task-file <path>.')
+    .description('Start the dispatcher: give the task to the lead. Use "<task>" or --task-file <path>. With --agent, give it to that one member alone.')
     .option("-p, --project <name>")
     .option("--task-file <path>", "read the task from a file")
+    .option("--agent <name>", "run only this member of the project, alone: it cannot mail teammates or ask you, and its own `done` ends the run")
+    .option("--assume-defaults", "when the run stops to ask, use the suggested answer for every question that has one")
     .action(async (task, opts) => {
     try {
         const pr = loadProject(opts.project);
@@ -202,7 +266,16 @@ program
             console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
         if (!res.ok)
             fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
-        await preflight(pr);
+        let checked = pr;
+        if (opts.agent) {
+            assertName("agent", opts.agent);
+            if (opts.assumeDefaults)
+                console.error("warn   --assume-defaults is ignored with --agent: a solo agent cannot ask questions.");
+            // Fails with the member list (and a hint for a global-only agent) before anything is written.
+            const sp = soloProject(pr, opts.agent, { globalAgents: Object.keys(loadGlobal(home()).agents) });
+            checked = onlyAgent(sp, opts.agent);
+        }
+        await preflight(checked);
         const runId = newRunId();
         const runDir = path.join(pr.paths.runs, runId);
         const lease = takeLock(pr, runId);
@@ -210,15 +283,15 @@ program
         const cancel = cancelOnSignals();
         try {
             const prepared = prepareTask({ text: task, file: opts.taskFile, cwd: process.cwd(), runDir });
-            console.log(`Project ${pr.name} — repo ${pr.dir}`);
+            console.log(`Project ${pr.name} — repo ${pr.dir}${opts.agent ? ` — solo: ${opts.agent}` : ""}`);
             console.log(`Task: ${prepared.source === "file" ? `file ${prepared.sourcePath}` : "text"} (${prepared.bytes} bytes${prepared.inline ? "" : ", passed by reference"})`);
-            summary = await runTeam({ project: pr, task: prepared, runDir, signal: cancel.signal });
+            summary = await runTeam({ project: pr, task: prepared, runDir, soloAgent: opts.agent, signal: cancel.signal });
         }
         finally {
             cancel.dispose();
             lease.release();
         }
-        reportRun(summary, runDir);
+        await driveRun(pr, runDir, summary, !!opts.assumeDefaults);
     }
     catch (e) {
         fail(e instanceof ConfigError ? e.message : e.message);
@@ -228,6 +301,7 @@ program
     .command("resume [run-id]")
     .description("Continue an interrupted (or failed) run: same run dir, sessions and round count; the task is not re-sent. Without an id, picks the newest run that is not done or running; with an id, continues that run.")
     .option("-p, --project <name>")
+    .option("--assume-defaults", "if the run waits for answers, use the suggested answer for every unanswered question that has one")
     .action(async (runId, opts) => {
     try {
         const pr = loadProject(opts.project);
@@ -236,7 +310,6 @@ program
             console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
         if (!res.ok)
             fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
-        await preflight(pr);
         let found;
         if (runId) {
             assertName("run", runId);
@@ -251,6 +324,8 @@ program
                 fail("No unfinished run to resume. Start one with: agent-lyceum run \"<task>\"");
         }
         const { dir, state } = found;
+        // A solo run needs only its own agent's runtime, as when it started.
+        await preflight(state.solo_agent ? onlyAgent(soloProject(pr, state.solo_agent), state.solo_agent) : pr);
         if (!state.end_reason && runIsAlive(state, pr))
             fail(`Run ${state.run_id} is still running (pid ${state.pid}).`);
         if (state.end_reason === "done") {
@@ -263,20 +338,51 @@ program
         }
         if (state.rounds >= pr.dispatcher.max_rounds)
             fail(`Run ${state.run_id} used ${state.rounds}/${pr.dispatcher.max_rounds} rounds; raise dispatcher.max_rounds in project.yaml first.`);
-        const lease = takeLock(pr, state.run_id);
-        let summary;
-        const cancel = cancelOnSignals();
-        try {
-            console.log(`Project ${pr.name} — repo ${pr.dir}`);
-            console.log(`Resuming run ${state.run_id} (${state.end_reason ?? "interrupted"}) at round ${state.rounds}/${pr.dispatcher.max_rounds}: ${state.task_summary}`);
-            // Read the state again under the lock: another process may have changed it while we were checking.
-            summary = await runTeam({ project: pr, resume: loadRunState(dir), runDir: dir, signal: cancel.signal });
+        if (state.end_reason === "waiting") {
+            const prep = prepareAnswers(dir, { assumeDefaults: !!opts.assumeDefaults });
+            if (!prep.complete) {
+                printWaiting(pr, state.run_id, prep.path, prep.problems);
+                process.exit(3);
+            }
         }
-        finally {
-            cancel.dispose();
-            lease.release();
+        const summary = await continueRun(pr, dir, state.run_id);
+        await driveRun(pr, dir, summary, !!opts.assumeDefaults);
+    }
+    catch (e) {
+        fail(e instanceof ConfigError ? e.message : e.message);
+    }
+});
+program
+    .command("answer <run-id>")
+    .description("Answer the questions a waiting run asked: opens ask-reply.md in $EDITOR, checks the answers, then continues the run. With --no-edit it only checks a file you already edited.")
+    .option("-p, --project <name>")
+    .option("--no-edit", "do not open the editor; check the file as it is")
+    .option("--assume-defaults", "use the suggested answer for every unanswered question that has one")
+    .action(async (runId, opts) => {
+    try {
+        assertName("run", runId);
+        const pr = loadProject(opts.project);
+        const dir = path.join(pr.paths.runs, runId);
+        if (!fs.existsSync(path.join(dir, "state.json")))
+            fail(`Run "${runId}" not found in ${pr.paths.runs}.`);
+        const state = loadRunState(dir);
+        if (state.end_reason !== "waiting")
+            fail(`Run ${runId} is not waiting for answers (${state.end_reason ?? "not finished"}).`);
+        if (opts.edit)
+            openInEditor(prepareAnswers(dir, {}).path);
+        const prep = prepareAnswers(dir, { assumeDefaults: !!opts.assumeDefaults });
+        if (!prep.complete) {
+            printWaiting(pr, runId, prep.path, prep.problems);
+            process.exit(3);
         }
-        reportRun(summary, dir);
+        const res = validateProject(pr);
+        for (const i of res.issues)
+            console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
+        if (!res.ok)
+            fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
+        await preflight(pr);
+        const summary = await continueRun(pr, dir, runId);
+        await driveRun(pr, dir, summary, !!opts.assumeDefaults);
     }
     catch (e) {
         fail(e instanceof ConfigError ? e.message : e.message);
@@ -407,6 +513,129 @@ program
         fail(e.message);
     }
 });
+program
+    .command("call <agent> [task]")
+    .description("Call one agent of the global library on its own, outside any project: it works in --dir (default: the current directory) and its final answer is printed. It cannot mail anyone or ask you.")
+    .option("--task-file <path>", "read the task from a file")
+    .option("--dir <path>", "the directory the agent works in (default: the current directory)")
+    .action(async (agentName, task, opts) => {
+    try {
+        if (task !== undefined && opts.taskFile)
+            fail("Give the task either as text or with --task-file, not both.");
+        const text = opts.taskFile ? readTaskFile(absPath(opts.taskFile, process.cwd())) : task;
+        if (!text?.trim())
+            fail("Give the task as text or with --task-file.");
+        const h = home();
+        const dir = absPath(opts.dir ?? ".", process.cwd());
+        const agent = resolveCallAgent(h, agentName);
+        await preflight(callProject(h, agent, dir, path.join(callsDir(h), "preflight")));
+        const cancel = cancelOnSignals();
+        let r;
+        try {
+            r = await callAgent({ home: h, agent: agentName, task: text, dir, signal: cancel.signal });
+        }
+        finally {
+            cancel.dispose();
+        }
+        console.error(`Call ${r.callId}: ${r.callDir}`);
+        if (r.cancelled)
+            fail("Cancelled.", 130);
+        if (!r.ok)
+            fail(`Call failed: ${r.error}\nLog: ${path.join(r.callDir, "log")}`);
+        console.log(r.text.trimEnd());
+    }
+    catch (e) {
+        fail(e instanceof ConfigError ? e.message : e.message);
+    }
+});
+const memoryCmd = program.command("memory").description("Look after the agents' long-term memory");
+function layerOpt(v) {
+    if (v === undefined || v === "project")
+        return "project";
+    if (v === "global")
+        return "global";
+    return fail(`--layer must be "project" or "global" (task memory is not tidied: \`clear\` deletes it).`);
+}
+memoryCmd
+    .command("tidy")
+    .description("Have agents tidy their own memory: merge duplicates, fix stale entries, archive what is obsolete (never deletes). Manual only; nothing triggers it automatically.")
+    .option("-p, --project <name>")
+    .option("--agent <name>", "tidy only this agent (default: every agent)")
+    .option("--layer <layer>", "project (default) or global; global memory is shared by every project, so it is never tidied unless you ask")
+    .option("--dry-run", "only show the memory sizes and what changed in the project; wake nobody, change nothing")
+    .action(async (opts) => {
+    try {
+        const layer = layerOpt(opts.layer);
+        const pr = loadProject(opts.project);
+        if (opts.dryRun) {
+            const dry = await tidyMemory({ project: pr, layer, agent: opts.agent, dryRun: true });
+            if (dry.length === 0)
+                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 use --layer global)." : "Set `memory.global` for an agent."}`);
+            return;
+        }
+        const res = validateProject(pr);
+        for (const i of res.issues)
+            console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
+        if (!res.ok)
+            fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
+        await preflight(pr);
+        const lease = takeLock(pr, `tidy-${tidyStamp()}`);
+        const cancel = cancelOnSignals();
+        let results;
+        try {
+            results = await tidyMemory({ project: pr, layer, agent: opts.agent, signal: cancel.signal });
+        }
+        finally {
+            cancel.dispose();
+            lease.release();
+        }
+        if (results.length === 0)
+            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 memory restore ${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`);
+                for (const p of r.problems)
+                    console.error(`    - ${p}`);
+            }
+        }
+        process.exit(results.some((r) => r.status === "failed") ? 1 : 0);
+    }
+    catch (e) {
+        fail(e instanceof ConfigError ? e.message : e.message);
+    }
+});
+memoryCmd
+    .command("restore <stamp>")
+    .description("Move the files of one tidy's archive back (nothing that exists now is overwritten) and re-add them to MEMORY.md")
+    .option("-p, --project <name>")
+    .requiredOption("--agent <name>")
+    .option("--layer <layer>", "project (default) or global")
+    .action((stamp, opts) => {
+    try {
+        const layer = layerOpt(opts.layer);
+        const pr = loadProject(opts.project);
+        const lease = takeLock(pr, `restore-${tidyStamp()}`);
+        try {
+            const r = restoreMemory({ project: pr, agent: opts.agent, layer, stamp });
+            for (const f of r.restored)
+                console.log(`  restored  ${f}`);
+            for (const s of r.skipped)
+                console.log(`  skipped   ${s.rel}: ${s.reason}`);
+            if (!r.restored.length && !r.skipped.length)
+                console.log(`Archive ${stamp} holds no files to restore.`);
+        }
+        finally {
+            lease.release();
+        }
+    }
+    catch (e) {
+        fail(e.message);
+    }
+});
 function useColor() {
     if (process.env.NO_COLOR)
         return false;

package/dist/config.d.ts

@@ -18,6 +18,8 @@ export interface ResolvedAgent {
     resume: boolean;
     canMessage: "all" | string[];
     canEditAgentMd: boolean;
+    /** May send `type: ask` mail to the user (the run then waits for the answer). */
+    canAskUser: boolean;
     owns: string[];
     /** Where each field's value came from (for `validate` output). */
     sources: Record<string, Source>;
@@ -39,6 +41,8 @@ export interface ResolvedProject {
     };
     /** Agents working in their own git worktree instead of `dir` (set by the dispatcher for the wake-ups in progress). */
     workspaces?: Record<string, AgentWorkspace>;
+    /** Set for a single agent working alone: "run" = inside a run of this project (`run --agent`), "call" = outside any project (`call`). */
+    solo?: "run" | "call";
 }
 export declare function loadGlobal(home: string): {
     agents: Record<string, {
@@ -53,6 +57,7 @@ export declare function loadGlobal(home: string): {
         resume?: boolean | undefined;
         can_message?: "all" | string[] | undefined;
         can_edit_agent_md?: boolean | undefined;
+        can_ask_user?: boolean | undefined;
         owns?: string[] | undefined;
     }>;
 };
@@ -82,10 +87,13 @@ export declare function loadProjectRaw(home: string, name: string): {
         resume?: boolean | undefined;
         can_message?: "all" | string[] | undefined;
         can_edit_agent_md?: boolean | undefined;
+        can_ask_user?: boolean | undefined;
         owns?: string[] | undefined;
     }>;
 };
 export declare function resolveProject(home: string, name: string): ResolvedProject;
+/** The merge `resolveProject` does, from configs already read: `call` uses it with a made-up project that lists one global agent. */
+export declare function resolveProjectFrom(home: string, name: string, g: ReturnType<typeof loadGlobal>, p: ReturnType<typeof loadProjectRaw>): ResolvedProject;
 /** Registered projects: name -> repo dir (best effort; skips broken configs). */
 export declare function listProjects(home: string): {
     name: string;

package/dist/config.js

@@ -51,8 +51,10 @@ function resolveLayer(p, base) {
     return out;
 }
 export function resolveProject(home, name) {
-    const g = loadGlobal(home);
-    const p = loadProjectRaw(home, name);
+    return resolveProjectFrom(home, name, loadGlobal(home), loadProjectRaw(home, name));
+}
+/** The merge `resolveProject` does, from configs already read: `call` uses it with a made-up project that lists one global agent. */
+export function resolveProjectFrom(home, name, g, p) {
     const paths = projectPaths(home, name);
     const hp = homePaths(home);
     const lead = p.team.lead;
@@ -130,11 +132,13 @@ export function resolveProject(home, name) {
         const resume = pick("resume");
         const canMessage = pick("can_message");
         const canEdit = pick("can_edit_agent_md");
+        const canAsk = pick("can_ask_user");
         const owns = pick("owns");
         for (const [k, v] of [
             ["resume", resume],
             ["can_message", canMessage],
             ["can_edit_agent_md", canEdit],
+            ["can_ask_user", canAsk],
             ["owns", owns],
         ]) {
             if (v === undefined)
@@ -150,6 +154,7 @@ export function resolveProject(home, name) {
             resume: resume ?? isLead,
             canMessage: canMessage ?? (isLead ? "all" : [lead]),
             canEditAgentMd: canEdit ?? isLead,
+            canAskUser: canAsk ?? isLead,
             owns: owns ?? [],
             sources,
         };
@@ -198,7 +203,7 @@ export function findProjectForCwd(home, cwd) {
     }
     return best?.name;
 }
-const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "owns"];
+const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "can_ask_user", "owns"];
 /** The resolved project plus, for every setting, the file and key it was taken from (or "default"). */
 export function resolveProjectWithSources(home, name) {
     const project = resolveProject(home, name);
@@ -255,6 +260,7 @@ export function flattenResolved(project) {
         v[`${p}.resume`] = a.resume;
         v[`${p}.can_message`] = a.canMessage;
         v[`${p}.can_edit_agent_md`] = a.canEditAgentMd;
+        v[`${p}.can_ask_user`] = a.canAskUser;
         v[`${p}.owns`] = a.owns;
     }
     return v;

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { tidyAdvice } from "./memory-tidy.js";
 import { inspectProjectLock, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
@@ -132,6 +133,8 @@ export async function diagnoseProject(project, opts = {}) {
             message: alive ? `A run is active: ${lock.run_id} (pid ${lock.pid}).` : `A stale run lock is left by ${lock.run_id} (pid ${lock.pid} is gone); \`agent-lyceum unlock --force\` clears it.`,
         });
     }
+    for (const a of tidyAdvice(project))
+        checks.push({ level: "info", subject: "memory", message: `${a.agent}: ${a.reason}. Consider: agent-lyceum memory tidy -p ${project.name} --agent ${a.agent} (doctor only suggests; it never tidies).` });
     const runtimes = await probeProjectRuntimes(project, opts);
     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/mailbox.d.ts

@@ -3,7 +3,7 @@ import { type Step } from "./format.js";
 import { atomicWrite } from "./fs-util.js";
 import { RouteJournal } from "./message-store.js";
 export { atomicWrite };
-export declare const MESSAGE_TYPES: readonly ["task", "reply", "failure", "done"];
+export declare const MESSAGE_TYPES: readonly ["task", "reply", "failure", "done", "ask"];
 export type MessageType = (typeof MESSAGE_TYPES)[number];
 export interface MessageMeta {
     id: string;
@@ -88,6 +88,14 @@ export interface RouteResult {
         file: string;
         meta: Record<string, unknown>;
     };
+    /** Questions for the user. Like `done`, the file stays in the outbox until the caller has stored the questions. */
+    asks: {
+        from: string;
+        subject: string;
+        body: string;
+        file: string;
+        source: string;
+    }[];
     /** Latest `## Steps` checklist the lead sent, if any. */
     steps?: Step[];
 }

package/dist/mailbox.js

@@ -8,7 +8,7 @@ import { deterministicId, fault, RouteJournal, sourceIdOf } from "./message-stor
 import { inboxDir, outboxDir } from "./policy.js";
 import { must } from "./assert.js";
 export { atomicWrite };
-export const MESSAGE_TYPES = ["task", "reply", "failure", "done"];
+export const MESSAGE_TYPES = ["task", "reply", "failure", "done", "ask"];
 export function newId() {
     return crypto.randomBytes(3).toString("hex");
 }
@@ -165,7 +165,7 @@ export function rejectDone(file) {
 }
 /** Validate each agent's outbox and move accepted mail into recipients' inboxes. Safe to run again after a crash. */
 export function routeOutboxes(project) {
-    const res = { delivered: [], rejected: [], warnings: [] };
+    const res = { delivered: [], rejected: [], warnings: [], asks: [] };
     const journal = project.run ? new RouteJournal(project.run.dir) : undefined;
     for (const sender of Object.values(project.agents)) {
         const dir = outboxDir(project, sender.name);
@@ -207,10 +207,18 @@ export function routeOutboxes(project) {
             }
             const type = (d.type ?? "reply");
             if (!MESSAGE_TYPES.includes(type) || type === "failure") {
-                reject(`unknown or not allowed message type "${String(d.type)}" (use task, reply or done).`);
+                reject(`unknown or not allowed message type "${String(d.type)}" (use task, reply, ask or done).`);
                 continue;
             }
             const subject = String(d.subject ?? "(no subject)");
+            if (type === "ask") {
+                if (!sender.canAskUser) {
+                    reject(`you may not ask the user directly (can_ask_user is off for "${sender.name}"). Put the question in a reply to the lead ("${project.lead}"), who can ask.`);
+                    continue;
+                }
+                res.asks.push({ from: sender.name, subject, body: parsed.body, file, source });
+                continue;
+            }
             if (type === "done") {
                 if (sender.name !== project.lead) {
                     reject(`only the lead ("${project.lead}") may send a "done" message.`);

package/dist/memory-tidy.d.ts

@@ -0,0 +1,115 @@
+import { type Invoker } from "./adapters/index.js";
+import type { ResolvedProject } from "./config.js";
+export type Layer = "project" | "global";
+export declare const ARCHIVE_DIR = ".archive";
+export declare const TIDY_STATE_FILE = ".tidy-state.json";
+export declare const TIDY_REPORT_FILE = "tidy-report.md";
+export declare const STAMP_RE: RegExp;
+/** `20261008T031500Z`: UTC, sortable, safe in a file name. */
+export declare const tidyStamp: (d?: Date) => string;
+export interface MemoryTarget {
+    agent: string;
+    layer: Layer;
+    dir: string;
+}
+/** The memory directories to tidy. Without `agent`, every agent that has a directory for the layer; with it, that agent or an error. */
+export declare function targetsFor(project: ResolvedProject, opts: {
+    layer: Layer;
+    agent?: string;
+}): MemoryTarget[];
+export interface MemoryFile {
+    rel: string;
+    bytes: number;
+    mtime: string;
+}
+/** Every file under `dir` (the archive included, the state file not), `/`-separated and sorted. */
+export declare function listMemoryFiles(dir: string): MemoryFile[];
+export interface MemoryStats {
+    files: number;
+    bytes: number;
+    indexBytes: number;
+    oldest?: string;
+    newest?: string;
+}
+/** Size and age of the live files (the archive is not counted). */
+export declare function memoryStats(dir: string): MemoryStats;
+/** Content hash of every file (the archive included), to tell whether a directory changed. */
+export declare function fingerprint(dir: string): Record<string, string>;
+/** Copy each directory aside (a directory that does not exist is remembered as absent). */
+export declare function snapshotDirs(dirs: string[], into: string): void;
+/** Put each directory back as `snapshotDirs` saw it, removing whatever was added since. */
+export declare function restoreDirs(dirs: string[], from: string): void;
+/**
+ * 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 declare function verifyConservation(before: string[], dir: string, stamp: string): string[];
+export interface TidyState {
+    /** HEAD of the project repo when the last tidy finished. */
+    head?: string;
+    at: string;
+    /** The archive folder of that tidy. */
+    archive?: string;
+}
+export declare function readTidyState(dir: string): TidyState | undefined;
+export declare function writeTidyState(dir: string, st: TidyState): void;
+export interface ProjectChanges {
+    head?: string;
+    since?: string;
+    log: string[];
+    stat: string[];
+    note?: string;
+}
+export declare function projectChanges(repoDir: string, since?: string): ProjectChanges;
+export interface MissingPath {
+    file: string;
+    path: string;
+}
+/** Backticked paths in the live Markdown files of `dir` that do not exist. Relative ones are looked up in `repoDir` (skipped without it). */
+export declare function findMissingPaths(dir: string, repoDir: string | undefined): MissingPath[];
+export interface TidyOptions {
+    project: ResolvedProject;
+    layer: Layer;
+    agent?: string;
+    dryRun?: boolean;
+    invoker?: Invoker;
+    signal?: AbortSignal;
+    say?: (line: string) => void;
+    now?: () => Date;
+}
+export interface TidyResult {
+    agent: string;
+    layer: Layer;
+    dir: string;
+    status: "tidied" | "skipped" | "failed" | "dry-run";
+    /** The archive stamp of a finished tidy. */
+    archive?: string;
+    problems: string[];
+}
+/** Scratch space of one tidy (snapshot and the invocation's logs); outside every memory dir and every run. */
+export declare const tidyWorkDir: (project: ResolvedProject, stamp: string, agent: string) => string;
+/** Tidy the memory of the chosen agents, one after another. Only ever called by a person (`agent-lyceum memory tidy`). */
+export declare function tidyMemory(o: TidyOptions): Promise<TidyResult[]>;
+export interface RestoreResult {
+    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. */
+export declare function restoreMemory(o: {
+    project: ResolvedProject;
+    agent: string;
+    layer: Layer;
+    stamp: string;
+}): RestoreResult;
+/** The stamps of the archives in a memory directory, oldest first. */
+export declare function listArchives(dir: string): string[];
+export declare const ADVICE_COMMITS = 50;
+export interface TidyAdvice {
+    agent: string;
+    reason: string;
+}
+/** Hints only: project memory whose index is larger than what an agent is shown, or whose baseline is far behind. Never acts. */
+export declare function tidyAdvice(project: ResolvedProject): TidyAdvice[];