agent-lyceum 0.4.14 → 0.6.0

package/dist/cli.js

@@ -4,6 +4,8 @@ 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 { 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";
@@ -15,6 +17,7 @@ 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 { formatEnforcement, validateProject } from "./validate.js";
+import { must } from "./assert.js";
 const program = new Command();
 program
     .name("agent-lyceum")
@@ -170,9 +173,13 @@ function cancelOnSignals() {
     const onTerm = handler("Terminated");
     process.on("SIGINT", onInt);
     process.on("SIGTERM", onTerm);
-    return { signal: ac.signal, dispose: () => (process.off("SIGINT", onInt), process.off("SIGTERM", onTerm)) };
+    return { signal: ac.signal, dispose: () => {
+            process.off("SIGINT", onInt);
+            process.off("SIGTERM", onTerm);
+        },
+    };
 }
-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}`);
@@ -182,13 +189,72 @@ 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>.')
     .option("-p, --project <name>")
     .option("--task-file <path>", "read the task from a file")
+    .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);
@@ -213,7 +279,7 @@ program
             cancel.dispose();
             lease.release();
         }
-        reportRun(summary, runDir);
+        await driveRun(pr, runDir, summary, !!opts.assumeDefaults);
     }
     catch (e) {
         fail(e instanceof ConfigError ? e.message : e.message);
@@ -223,6 +289,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);
@@ -258,20 +325,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);
@@ -354,7 +452,7 @@ configCmd
         const keys = Object.keys(sources).filter((k) => values[k] !== undefined);
         const w = Math.max(...keys.map((k) => `${k} = ${show(values[k])}`.length));
         for (const k of keys)
-            console.log(`${`${k} = ${show(values[k])}`.padEnd(w)}   ${where(sources[k])}`);
+            console.log(`${`${k} = ${show(values[k])}`.padEnd(w)}   ${where(must(sources[k], `source of ${k}`))}`);
     }
     catch (e) {
         fail(e instanceof ConfigError ? e.message : e.message);
@@ -402,6 +500,94 @@ program
         fail(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>;
@@ -44,45 +46,48 @@ export declare function loadGlobal(home: string): {
     agents: Record<string, {
         runtime?: "claude-code" | "codex" | undefined;
         model?: string | undefined;
-        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
         agent_md?: string | undefined;
         memory?: {
             global?: string | undefined;
             project?: string | undefined;
         } | undefined;
         resume?: boolean | undefined;
-        can_message?: string[] | "all" | undefined;
+        can_message?: "all" | string[] | undefined;
         can_edit_agent_md?: boolean | undefined;
+        can_ask_user?: boolean | undefined;
         owns?: string[] | undefined;
     }>;
 };
 export declare function loadProjectRaw(home: string, name: string): {
+    dir: string;
+    team: {
+        lead: string;
+    };
+    dispatcher: {
+        max_rounds?: number | undefined;
+        max_parallel?: number | undefined;
+        wake_timeout_sec?: number | undefined;
+        retry?: number | undefined;
+        strict?: boolean | undefined;
+        workspace_mode?: "auto" | "shared" | "worktree" | undefined;
+        log_max_bytes?: number | undefined;
+    };
     agents: Record<string, {
         runtime?: "claude-code" | "codex" | undefined;
         model?: string | undefined;
-        effort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
         agent_md?: string | undefined;
         memory?: {
             global?: string | undefined;
             project?: string | undefined;
         } | undefined;
         resume?: boolean | undefined;
-        can_message?: string[] | "all" | undefined;
+        can_message?: "all" | string[] | undefined;
         can_edit_agent_md?: boolean | undefined;
+        can_ask_user?: boolean | undefined;
         owns?: string[] | undefined;
     }>;
-    dir: string;
-    team: {
-        lead: string;
-    };
-    dispatcher: {
-        strict?: boolean | undefined;
-        max_rounds?: number | undefined;
-        max_parallel?: number | undefined;
-        wake_timeout_sec?: number | undefined;
-        retry?: number | undefined;
-        workspace_mode?: "shared" | "auto" | "worktree" | undefined;
-    };
 };
 export declare function resolveProject(home: string, name: string): ResolvedProject;
 /** Registered projects: name -> repo dir (best effort; skips broken configs). */

package/dist/config.js

@@ -112,21 +112,31 @@ export function resolveProject(home, name) {
         let runtime = pl.runtime;
         if (runtime !== undefined)
             sources.runtime = "project";
-        else if ((runtime = inferRuntime(pl.model)))
-            sources.runtime = "model";
-        else if ((runtime = gl.runtime))
-            sources.runtime = "global";
-        else if ((runtime = inferRuntime(gl.model)))
-            sources.runtime = "model";
+        else {
+            const candidates = [
+                [inferRuntime(pl.model), "model"],
+                [gl.runtime, "global"],
+                [inferRuntime(gl.model), "model"],
+            ];
+            for (const [r, from] of candidates) {
+                if (!r)
+                    continue;
+                runtime = r;
+                sources.runtime = from;
+                break;
+            }
+        }
         const isLead = agentName === lead;
         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)
@@ -142,6 +152,7 @@ export function resolveProject(home, name) {
             resume: resume ?? isLead,
             canMessage: canMessage ?? (isLead ? "all" : [lead]),
             canEditAgentMd: canEdit ?? isLead,
+            canAskUser: canAsk ?? isLead,
             owns: owns ?? [],
             sources,
         };
@@ -190,7 +201,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);
@@ -247,6 +258,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/dispatcher.d.ts

@@ -1,37 +1,6 @@
-import { type Invoker } from "./adapters/index.js";
-import type { ResolvedProject } from "./config.js";
-import type { RunOutcome } from "./schema.js";
-import { newRunId, type EndReason, type RunState } from "./run-store.js";
-import { type PreparedTask } from "./task.js";
+import { type RunOptions, type RunSummary } from "./run-session.js";
+import { newRunId } from "./run-store.js";
 export { newRunId };
 export type { ActiveWake, EndReason, RunState, SentTopic, WakeRecord, WakeTopic } from "./run-store.js";
-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;
-export interface RunSummary {
-    runId: string;
-    runDir: string;
-    rounds: number;
-    endReason: EndReason;
-    /** How the work turned out; only "completed" means success. */
-    outcome: RunOutcome;
-    outcomeNote?: string;
-    verification?: string;
-    doneMessage?: {
-        subject: string;
-        body: string;
-    };
-}
-export interface RunOptions {
-    project: ResolvedProject;
-    /** 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. */
-    resume?: RunState;
-    runDir: string;
-    invoker?: Invoker;
-    /** Stop the run when this fires: running agents are killed, unread mail is kept, the run ends `cancelled` and can be resumed. */
-    signal?: AbortSignal;
-    log?: (line: string) => void;
-}
+export { MAX_DONE_REJECTIONS, RESULT_FILE, type RunOptions, type RunSummary } from "./run-session.js";
 export declare function runTeam(opts: RunOptions): Promise<RunSummary>;