agent-lyceum 0.4.9

package/dist/run-cleanup.js

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+import { assertName } from "./paths.js";
+import { loadRunState } from "./run-store.js";
+import { runIsAlive } from "./status.js";
+import { deleteSnapshotRefs, inspectWorkspace, listSnapshotRefs, listWorkspaceAgents, removeAgentWorkspace } from "./worktree.js";
+const journalDir = (p) => path.join(p.paths.root, "cleanup");
+const journalFile = (p, runId) => path.join(journalDir(p), `${runId}.json`);
+const lexists = (p) => {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * What clearing a run would do. Deletes nothing. Refuses (see `refusals`) while the run is running, or while
+ * a worktree holds work that is not in the repo, unless `keepWorktrees` keeps the worktrees and their branches.
+ */
+export function planRunCleanup(project, runId, opts = {}) {
+    assertName("run", runId);
+    const keepWorktrees = !!opts.keepWorktrees;
+    const runDir = path.join(project.paths.runs, runId);
+    const hasRun = lexists(path.join(runDir, "state.json"));
+    const hasJournal = fs.existsSync(journalFile(project, runId));
+    if (!hasRun && !hasJournal)
+        throw new Error(`Run "${runId}" not found in ${project.paths.runs}. List ids with: agent-lyceum status --task-list`);
+    const plan = { project, runId, runDir, keepWorktrees, items: [], refusals: [], keep: [], summary: runId };
+    if (hasRun) {
+        const state = loadRunState(runDir);
+        plan.summary = `${runId}: ${state.task_summary}`;
+        if (!state.end_reason && runIsAlive(state, project))
+            plan.refusals.push(`Run ${runId} is still running (pid ${state.pid}); stop it first.`);
+    }
+    for (const agent of listWorkspaceAgents(project, runId)) {
+        const w = inspectWorkspace(project, runId, agent);
+        if (!w)
+            continue;
+        const files = [...new Set([...w.dirty, ...w.unintegrated])];
+        const holdsWork = files.length > 0 || !!w.unknown;
+        if (keepWorktrees || holdsWork) {
+            plan.keep.push({ agent, branch: w.branch, path: w.root, files: files.length ? files : w.unknown ? [`(${w.unknown})`] : [] });
+            if (holdsWork && !keepWorktrees) {
+                plan.refusals.push(`${agent} has work that is not in the repo: ${files.length ? files.join(", ") : w.unknown} (branch ${w.branch}, worktree ${w.root}). ` +
+                    `Bring it in or discard it by hand, or use --keep-worktrees to keep the worktree and branch and clear the rest.`);
+            }
+            continue;
+        }
+        plan.items.push({ kind: "workspace", agent, path: w.root, label: `worktree and branch of ${agent} (${w.root}, ${w.branch}): its work is in the repo` });
+    }
+    if (!keepWorktrees && listSnapshotRefs(project, runId).length) {
+        plan.items.push({ kind: "refs", label: `snapshot refs refs/agent-lyceum/${runId}/*` });
+    }
+    const mem = path.join(project.paths.taskMemory, runId);
+    if (lexists(mem))
+        plan.items.push({ kind: "task-memory", path: mem, label: `task memory ${mem}` });
+    if (hasRun || lexists(runDir))
+        plan.items.push({ kind: "run", path: runDir, label: `run directory ${runDir} (state, log, result, snapshots, mailboxes)` });
+    return plan;
+}
+/** Remove a path without ever following a symlink, and only inside the project home. */
+function safeRemove(project, target) {
+    if (!lexists(target))
+        return;
+    if (fs.lstatSync(target).isSymbolicLink()) {
+        fs.unlinkSync(target); // the link, never what it points to
+        return;
+    }
+    const root = fs.realpathSync(project.paths.root);
+    const inside = (p) => p === root || p.startsWith(root + path.sep);
+    if (!inside(fs.realpathSync(path.dirname(target))) || !inside(fs.realpathSync(target))) {
+        throw new Error(`refusing to delete ${target}: it is not inside the project home ${project.paths.root}`);
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+}
+/**
+ * Carry out a plan, step by step. Progress is written to a journal in the project home (outside the run being
+ * deleted), so an interrupted clear can simply be repeated. Stops at the first step that fails, leaving the run
+ * directory in place for the retry.
+ */
+export function executeRunCleanup(plan, hooks = {}) {
+    if (plan.refusals.length)
+        throw new Error(`Cleanup refused:\n${plan.refusals.map((r) => `- ${r}`).join("\n")}`);
+    const { project, runId } = plan;
+    const report = { done: [], failed: [] };
+    const jf = journalFile(project, runId);
+    const record = (state) => atomicWrite(jf, JSON.stringify({ run_id: runId, ...state }, null, 2));
+    const journal = { started_at: new Date().toISOString(), items: plan.items.map((i) => ({ ...i, done: false })) };
+    record(journal);
+    for (let n = 0; n < plan.items.length; n++) {
+        const item = plan.items[n];
+        try {
+            if (item.kind === "workspace") {
+                removeAgentWorkspace(project, runId, item.agent);
+                const dir = path.dirname(item.path);
+                if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0)
+                    fs.rmdirSync(dir);
+            }
+            else if (item.kind === "refs")
+                deleteSnapshotRefs(project, runId);
+            else
+                safeRemove(project, item.path);
+        }
+        catch (e) {
+            report.failed.push({ item, error: e.message });
+            return report; // keep the journal and the run directory: the next `clear` picks up here
+        }
+        report.done.push(item);
+        journal.items[n].done = true;
+        record(journal);
+        hooks.afterItem?.(item);
+    }
+    fs.rmSync(jf, { force: true });
+    if (fs.existsSync(journalDir(project)) && fs.readdirSync(journalDir(project)).length === 0)
+        fs.rmdirSync(journalDir(project));
+    return report;
+}

package/dist/run-store.d.ts

@@ -0,0 +1,111 @@
+import type { ResolvedProject } from "./config.js";
+import type { Step } from "./format.js";
+import type { RunOutcome } from "./schema.js";
+export declare const STATE_FILE = "state.json";
+export declare const STATE_SCHEMA_VERSION = 2;
+export type EndReason = "done" | "idle" | "max_rounds" | "lead_failed" | "cancelled";
+export type MailLayout = "run" | "legacy";
+export interface WakeTopic {
+    from: string;
+    type: string;
+    subject: string;
+    /** What the message is about, in one line. */
+    brief?: string;
+}
+export interface SentTopic {
+    to: string;
+    type: string;
+    subject: string;
+}
+export interface ActiveWake {
+    round: number;
+    since: string;
+    handling: WakeTopic[];
+}
+export interface WakeRecord {
+    round: number;
+    agent: string;
+    at: string;
+    duration_ms: number;
+    ok: boolean;
+    output_tokens?: number;
+    handling: WakeTopic[];
+    /** Mail this wake handed to others; `to` is "(done)" for the lead's final message. */
+    sent?: SentTopic[];
+    error?: string;
+}
+export interface RunState {
+    /** 1 for runs written before versioning; 2 for runs with their own mailboxes. */
+    schema_version: number;
+    /** "run": mail lives under the run dir. "legacy": the shared project mailboxes of older versions. */
+    mail_layout: MailLayout;
+    run_id: string;
+    project: string;
+    task_source: "text" | "file";
+    task_path?: string;
+    started_at: string;
+    ended_at?: string;
+    rounds: number;
+    max_rounds: number;
+    end_reason?: EndReason;
+    /** How the work turned out; absent on runs that ended before outcomes existed. */
+    outcome?: RunOutcome;
+    /** Why the outcome is not what the lead declared (completion contract not met, legacy done, ...). */
+    outcome_note?: string;
+    /** First lines of the lead's `## Verification`, for display. */
+    verification?: string;
+    /** How many `done` mails were sent back because they broke the completion contract. */
+    done_rejections?: number;
+    /** Recovery remarks (interrupted attempts whose side effects may have happened). */
+    notes?: string[];
+    /** "worktree": non-lead agents work in their own git worktrees. */
+    workspace_mode?: "shared" | "worktree";
+    /** Agents whose finished work could not be brought into the repo yet; their work is kept on their branch. */
+    blocked_integrations?: {
+        agent: string;
+        branch: string;
+        reason: string;
+        report: string;
+    }[];
+    /** Snapshots of the repo taken so far (`refs/agent-lyceum/<run>/base-<n>`). */
+    snapshots?: number;
+    sessions: Record<string, string>;
+    output_tokens: number;
+    last_wake: Record<string, {
+        at: string;
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Process running this dispatcher, so a monitor can tell "running" from "interrupted". */
+    pid: number;
+    /** One line describing the run's task. */
+    task_summary: string;
+    /** Agents being woken right now and what they were asked to handle. */
+    active: Record<string, ActiveWake>;
+    /** Finished wakes, oldest first. */
+    wakes: WakeRecord[];
+    /** Checklist progress: seeded from the task, then replaced by the lead's latest `## Steps`. */
+    steps?: Step[];
+}
+/** `20261006T010203456Z-<128 random bits>`: sorts by start time and cannot collide, even for two starts in one millisecond. */
+export declare function newRunId(d?: Date): string;
+/** A fresh v2 state; every collection present. */
+export declare function newRunState(init: Partial<RunState> & {
+    run_id: string;
+}): RunState;
+/** Read and validate `<runDir>/state.json`; throws an error naming the file and the problem. */
+export declare function loadRunState(runDir: string): RunState;
+export declare function saveRunState(runDir: string, state: RunState): void;
+/**
+ * The project as one run sees it. Per-task memory is always private to the run. With the "run" layout the
+ * mailboxes live inside the run dir; with "legacy" they stay the shared project mailboxes older versions used.
+ */
+export declare function bindRunProject(project: ResolvedProject, runDir: string, layout: MailLayout): ResolvedProject;
+/**
+ * How a finished run turned out. Runs that ended before outcomes existed have none recorded: they read as
+ * partial (failed for a failed lead) and `verified: false`, never as a success nobody checked.
+ */
+export declare function outcomeOf(s: Pick<RunState, "outcome" | "end_reason">): {
+    outcome: RunOutcome;
+    verified: boolean;
+} | undefined;

package/dist/run-store.js

@@ -0,0 +1,119 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { atomicWrite } from "./fs-util.js";
+export const STATE_FILE = "state.json";
+export const STATE_SCHEMA_VERSION = 2;
+/** `20261006T010203456Z-<128 random bits>`: sorts by start time and cannot collide, even for two starts in one millisecond. */
+export function newRunId(d = new Date()) {
+    const t = d.toISOString().replace(/[-:]/g, "").replace(/\.(\d+)Z$/, "$1Z");
+    return `${t}-${crypto.randomBytes(16).toString("hex")}`;
+}
+const nonNeg = z.number().finite();
+const WireState = z
+    .object({
+    schema_version: z.number().int().optional(),
+    mail_layout: z.enum(["run", "legacy"]).optional(),
+    run_id: z.string().min(1),
+    project: z.string().optional(),
+    task_source: z.enum(["text", "file"]).optional(),
+    task_path: z.string().optional(),
+    started_at: z.string().optional(),
+    ended_at: z.string().optional(),
+    rounds: nonNeg.optional(),
+    max_rounds: nonNeg.optional(),
+    end_reason: z.enum(["done", "idle", "max_rounds", "lead_failed", "cancelled"]).optional(),
+    outcome: z.enum(["completed", "partial", "blocked", "failed", "cancelled"]).optional(),
+    outcome_note: z.string().optional(),
+    verification: z.string().optional(),
+    done_rejections: nonNeg.optional(),
+    notes: z.array(z.string()).optional(),
+    sessions: z.record(z.string()).optional(),
+    output_tokens: nonNeg.optional(),
+    last_wake: z.record(z.any()).optional(),
+    pid: z.number().optional(),
+    task_summary: z.string().optional(),
+    active: z.record(z.any()).optional(),
+    wakes: z.array(z.any()).optional(),
+    steps: z.array(z.object({ text: z.string(), done: z.boolean() })).optional(),
+})
+    .passthrough();
+/** A fresh v2 state; every collection present. */
+export function newRunState(init) {
+    return normalize({ ...init, schema_version: STATE_SCHEMA_VERSION, mail_layout: init.mail_layout ?? "run" });
+}
+function normalize(w) {
+    const version = w.schema_version ?? 1;
+    return {
+        ...w,
+        schema_version: version,
+        mail_layout: version >= 2 ? (w.mail_layout ?? "run") : "legacy",
+        run_id: w.run_id,
+        project: w.project ?? "",
+        task_source: w.task_source ?? "text",
+        started_at: w.started_at ?? "",
+        rounds: w.rounds ?? 0,
+        max_rounds: w.max_rounds ?? 0,
+        sessions: w.sessions ?? {},
+        output_tokens: w.output_tokens ?? 0,
+        last_wake: w.last_wake ?? {},
+        pid: w.pid ?? 0,
+        task_summary: w.task_summary ?? "",
+        active: w.active ?? {},
+        wakes: w.wakes ?? [],
+    };
+}
+/** Read and validate `<runDir>/state.json`; throws an error naming the file and the problem. */
+export function loadRunState(runDir) {
+    const file = path.join(runDir, STATE_FILE);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        throw new Error(`Run state not found: ${file}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`Run state is not valid JSON (${file}): ${e.message}`);
+    }
+    const parsed = WireState.safeParse(raw);
+    if (!parsed.success) {
+        const msg = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        throw new Error(`Run state is invalid (${file}): ${msg}`);
+    }
+    if ((parsed.data.schema_version ?? 1) > STATE_SCHEMA_VERSION) {
+        throw new Error(`Run state ${file} uses schema_version ${parsed.data.schema_version}, newer than this agent-lyceum understands (${STATE_SCHEMA_VERSION}). Upgrade agent-lyceum.`);
+    }
+    return normalize(parsed.data);
+}
+export function saveRunState(runDir, state) {
+    atomicWrite(path.join(runDir, STATE_FILE), JSON.stringify(state, null, 2));
+}
+/**
+ * The project as one run sees it. Per-task memory is always private to the run. With the "run" layout the
+ * mailboxes live inside the run dir; with "legacy" they stay the shared project mailboxes older versions used.
+ */
+export function bindRunProject(project, runDir, layout) {
+    const runId = path.basename(runDir);
+    const agents = Object.fromEntries(Object.entries(project.agents).map(([n, a]) => [n, { ...a, memory: { ...a.memory, task: path.join(project.paths.taskMemory, runId, n) } }]));
+    const paths = layout === "run"
+        ? { ...project.paths, inboxRoot: path.join(runDir, "mail", "inbox"), outboxRoot: path.join(runDir, "mail", "outbox") }
+        : project.paths;
+    return { ...project, agents, paths, run: { id: runId, dir: runDir, layout } };
+}
+/**
+ * How a finished run turned out. Runs that ended before outcomes existed have none recorded: they read as
+ * partial (failed for a failed lead) and `verified: false`, never as a success nobody checked.
+ */
+export function outcomeOf(s) {
+    if (s.outcome)
+        return { outcome: s.outcome, verified: true };
+    if (!s.end_reason)
+        return undefined;
+    return { outcome: s.end_reason === "lead_failed" ? "failed" : s.end_reason === "cancelled" ? "cancelled" : "partial", verified: false };
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,11 @@
+export interface InitResult {
+    home: string;
+    created: string[];
+    skipped: string[];
+}
+export declare function initHome(home: string): InitResult;
+export declare function addProject(home: string, name: string, dir: string): {
+    root: string;
+    config: string;
+};
+export declare function removeProject(home: string, name: string, purge: boolean): string;

package/dist/scaffold.js

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertName, homePaths, projectPaths } from "./paths.js";
+const PERSONAS = {
+    lead: `# Lead
+
+You coordinate the team. You receive the user's task, break it into concrete pieces, and delegate each piece to the right teammate by mail.
+
+- Keep \`COMMON.md\` (shared team context: goal, architecture decisions, conventions) accurate and short.
+- Write every task with the standard task headings, and cite the mail it derives from under Upstream so teammates can trace it.
+- When a teammate reports back, decide the next step: assign follow-up work, ask another teammate to verify, or accept the result.
+- Teammates cannot message each other by default; route everything through yourself.
+- When the whole job is verified and finished, send a \`done\` message summarising what was delivered.
+`,
+    "fe-member": `# Frontend member
+
+You implement frontend work assigned by the lead: components, pages, styling, client-side logic.
+
+- Read the lead's message carefully and restate the acceptance criteria to yourself before editing.
+- Keep changes small and focused; run the project's own checks (lint, type-check, tests) when they exist.
+- Fill the standard reply headings: list changed files under Changes, how you checked them under Verification, and note anything unfinished or risky.
+`,
+    "qa-member": `# QA member
+
+You verify work: run and write tests, reproduce bugs, and review changes against the acceptance criteria.
+
+- Do not fix product code yourself unless the lead asks; report findings to the lead with clear reproduction steps.
+- Prefer concrete evidence (commands run, output, failing test names) over opinions.
+- Besides the standard reply headings, add a \`## Verdict\` section containing \`pass\` or \`fail\`, and put your prioritised list of issues under Open items.
+`,
+};
+const GLOBAL_TEAM_YAML = `# Global agent library. Projects pick agents from here by name and may override any field.
+# Relative paths here are resolved against this folder. "~" is allowed.
+agents:
+  lead:
+    runtime: claude-code        # claude-code | codex
+    agent_md: agents/lead/AGENT.md
+    memory: { global: agents/lead/memory }
+  fe-member:
+    runtime: claude-code
+    agent_md: agents/fe-member/AGENT.md
+    memory: { global: agents/fe-member/memory }
+  qa-member:
+    runtime: claude-code
+    agent_md: agents/qa-member/AGENT.md
+    memory: { global: agents/qa-member/memory }
+`;
+export function initHome(home) {
+    const hp = homePaths(home);
+    const created = [];
+    const skipped = [];
+    const writeOnce = (file, content) => {
+        if (fs.existsSync(file)) {
+            skipped.push(file);
+            return;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, content);
+        created.push(file);
+    };
+    fs.mkdirSync(hp.projectsDir, { recursive: true });
+    writeOnce(hp.globalConfig, GLOBAL_TEAM_YAML);
+    for (const [name, text] of Object.entries(PERSONAS)) {
+        writeOnce(path.join(hp.globalAgentsDir, name, "AGENT.md"), text);
+        fs.mkdirSync(path.join(hp.globalAgentsDir, name, "memory"), { recursive: true });
+    }
+    return { home, created, skipped };
+}
+export function addProject(home, name, dir) {
+    assertName("project", name);
+    const hp = homePaths(home);
+    if (!fs.existsSync(hp.globalConfig)) {
+        throw new Error(`Not initialised: ${hp.globalConfig} is missing. Run \`agent-lyceum init\` first.`);
+    }
+    const repo = path.resolve(dir);
+    if (!fs.existsSync(repo) || !fs.statSync(repo).isDirectory())
+        throw new Error(`--dir is not a directory: ${repo}`);
+    const pp = projectPaths(home, name);
+    if (fs.existsSync(pp.config))
+        throw new Error(`Project "${name}" already exists (${pp.config}).`);
+    fs.mkdirSync(path.join(pp.shared, "common"), { recursive: true });
+    fs.mkdirSync(pp.runs, { recursive: true });
+    const yaml = `# Project "${name}". Paths here are relative to this folder; "~" is allowed.
+dir: ${repo}            # the repo the agents work in (the tool never writes config into it)
+team:
+  lead: lead
+dispatcher:
+  max_rounds: 30        # stop after this many agent wake-ups
+  max_parallel: 1       # >1 needs non-overlapping "owns" for every non-lead agent, and a git repo
+  workspace_mode: auto  # auto = a git worktree per non-lead agent when max_parallel > 1; shared | worktree to force
+  wake_timeout_sec: 600
+  retry: 1
+  strict: false         # true = refuse to start unless context protection is OS-enforced
+agents:
+  # Fields not set here are inherited from the global team.yaml.
+  lead:
+    resume: true        # keep the lead's session between wake-ups
+    can_message: all
+    can_edit_agent_md: true
+  fe-member:
+    can_message: [lead]
+    # owns: ["src/web/**"]
+    # memory: { project: agents/fe-member/memory }
+  qa-member:
+    can_message: [lead]
+    # owns: ["tests/**"]
+`;
+    fs.writeFileSync(pp.config, yaml);
+    const common = path.join(pp.shared, "common", "COMMON.md");
+    if (!fs.existsSync(common)) {
+        fs.writeFileSync(common, `# ${name} — shared team context\n\n(The lead maintains this file. Goal, architecture decisions, conventions. Keep it under 8 KB.)\n`);
+    }
+    return { root: pp.root, config: pp.config };
+}
+export function removeProject(home, name, purge) {
+    const pp = projectPaths(home, name);
+    if (!fs.existsSync(pp.config))
+        throw new Error(`Project "${name}" is not registered.`);
+    if (purge) {
+        fs.rmSync(pp.root, { recursive: true, force: true });
+        return `Removed ${pp.root} (registration and all context).`;
+    }
+    const dest = `${pp.config}.removed-${Date.now()}`;
+    fs.renameSync(pp.config, dest);
+    return `Unregistered "${name}". Context kept in ${pp.root} (config renamed to ${path.basename(dest)}). Use --purge to delete it.`;
+}