agent-lyceum 0.4.14 → 0.6.0

package/dist/project-lock.js

@@ -7,11 +7,46 @@ import { atomicWrite } from "./fs-util.js";
 export const LOCK_FILE = "lock.json";
 const RECLAIM_FILE = "lock.json.reclaim";
 const HEARTBEAT_MS = 5000;
+/** Field 22 (starttime, in clock ticks) of a /proc/<pid>/stat line. The command name (field 2) may contain spaces and ")". */
+export function parseProcStat(text) {
+    const end = text.lastIndexOf(")");
+    if (end < 0)
+        return undefined;
+    const fields = text.slice(end + 2).split(" "); // fields[0] is field 3 (state), so field 22 is fields[19]
+    const v = fields[19];
+    return v && /^\d+$/.test(v) ? v : undefined;
+}
+/** A start time that identifies one process: `proc:<ticks>` on Linux, the `ps` text elsewhere or when /proc cannot be read. */
+export function pidStartFrom(pid, io) {
+    if (io.platform === "linux") {
+        const text = io.readFile(`/proc/${pid}/stat`);
+        const ticks = text ? parseProcStat(text) : undefined;
+        if (ticks)
+            return `proc:${ticks}`;
+    }
+    return io.ps(pid);
+}
+const realIo = {
+    platform: process.platform,
+    readFile: (p) => {
+        try {
+            return fs.readFileSync(p, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    },
+    ps: (pid) => {
+        const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" });
+        const out = r.status === 0 ? r.stdout.trim() : "";
+        return out || undefined;
+    },
+};
 function pidStart(pid) {
-    const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" });
-    const out = r.status === 0 ? r.stdout.trim() : "";
-    return out || undefined;
+    return pidStartFrom(pid, realIo);
 }
+/** Two start times can only be compared when they were taken the same way. */
+const sameKind = (a, b) => a.startsWith("proc:") === b.startsWith("proc:");
 function readLock(root) {
     let text;
     try {
@@ -49,7 +84,7 @@ export function lockHolderAlive(info) {
     }
     if (info.pid_started) {
         const now = pidStart(info.pid);
-        if (now && now !== info.pid_started)
+        if (now && sameKind(now, info.pid_started) && now !== info.pid_started)
             return false;
     }
     return true;

package/dist/prompt.d.ts

@@ -1,5 +1,6 @@
 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;
@@ -9,3 +10,22 @@ export declare function buildSystemPrompt(project: ResolvedProject, agent: Resol
 /** 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

@@ -32,15 +32,33 @@ export function buildSystemPrompt(project, agent) {
     lines.push(readPersona(agent), "", "---", "", "# Team protocol (injected by agent-lyceum)", "");
     lines.push(`You are **${agent.name}**, a member of the team "${project.name}". You work in the repository \`${repoDirFor(project, agent.name)}\`.`, ...(project.workspaces?.[agent.name]
         ? [
-            `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.`,
+            `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 +141,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-cleanup.js

@@ -5,6 +5,7 @@ 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";
+import { must } from "./assert.js";
 const journalDir = (p) => path.join(p.paths.root, "cleanup");
 const journalFile = (p, runId) => path.join(journalDir(p), `${runId}.json`);
 const lexists = (p) => {
@@ -58,7 +59,7 @@ export function planRunCleanup(project, runId, opts = {}) {
     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)` });
+        plan.items.push({ kind: "run", path: runDir, label: `run directory ${runDir} (state, log, result, snapshots, kept violations, mailboxes)` });
     return plan;
 }
 /** Remove a path without ever following a symlink, and only inside the project home. */
@@ -91,7 +92,7 @@ export function executeRunCleanup(plan, hooks = {}) {
     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];
+        const item = must(plan.items[n], "cleanup item");
         try {
             if (item.kind === "workspace") {
                 removeAgentWorkspace(project, runId, item.agent);
@@ -109,7 +110,7 @@ export function executeRunCleanup(plan, hooks = {}) {
             return report; // keep the journal and the run directory: the next `clear` picks up here
         }
         report.done.push(item);
-        journal.items[n].done = true;
+        must(journal.items[n], "journal item").done = true;
         record(journal);
         hooks.afterItem?.(item);
     }

package/dist/run-log.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Append-only run log, one JSON object per line. When the next line would push the file past `maxBytes`
+ * (0 = no limit) the file becomes `<name>.1.jsonl`, replacing an older one, and a new file starts.
+ */
+export declare function createRunLog(file: string, maxBytes: number): (event: string, data?: Record<string, unknown>) => void;

package/dist/run-log.js

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+/**
+ * Append-only run log, one JSON object per line. When the next line would push the file past `maxBytes`
+ * (0 = no limit) the file becomes `<name>.1.jsonl`, replacing an older one, and a new file starts.
+ */
+export function createRunLog(file, maxBytes) {
+    let size = fs.existsSync(file) ? fs.statSync(file).size : 0;
+    return (event, data = {}) => {
+        const line = JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + "\n";
+        const bytes = Buffer.byteLength(line);
+        if (maxBytes > 0 && size > 0 && size + bytes > maxBytes) {
+            fs.renameSync(file, file.replace(/\.jsonl$/, ".1.jsonl"));
+            size = 0;
+        }
+        fs.appendFileSync(file, line);
+        size += bytes;
+    };
+}

package/dist/run-outcome.d.ts

@@ -0,0 +1,22 @@
+import type { DoneContract } from "./format.js";
+import type { EndReason } from "./run-store.js";
+import type { RunOutcome } from "./schema.js";
+export interface UnintegratedWork {
+    agent: string;
+    branch: string;
+    report: string;
+}
+/** What a lead's `done` amounts to: its declared outcome, unless the contract is broken or member work never reached the repo. */
+export declare function resolveDoneOutcome(contract: DoneContract, rejections: number, unintegrated: UnintegratedWork[]): {
+    outcome: RunOutcome;
+    note?: string;
+    verification?: string;
+};
+/** How a run turned out, from why it stopped (`done` carries the lead's own verdict). */
+export declare function endOutcome(endReason: EndReason, done?: {
+    outcome: RunOutcome;
+    note?: string;
+}): {
+    outcome: RunOutcome;
+    note?: string;
+};

package/dist/run-outcome.js

@@ -0,0 +1,28 @@
+/** What a lead's `done` amounts to: its declared outcome, unless the contract is broken or member work never reached the repo. */
+export function resolveDoneOutcome(contract, rejections, unintegrated) {
+    const ok = contract.missing.length === 0;
+    let outcome = ok ? (contract.outcome ?? "partial") : "partial";
+    let note = ok ? undefined : `Completion contract not met after ${rejections} reminder(s): missing ${contract.missing.join("; ")}. Reported as partial; the lead's report is kept as written.`;
+    if (outcome === "completed" && unintegrated.length) {
+        outcome = "blocked";
+        note = `Not completed: work of ${unintegrated.map((b) => `${b.agent} (branch ${b.branch})`).join(", ")} was never brought into the repo; see ${unintegrated.map((b) => b.report).join(", ")}.`;
+    }
+    return { outcome, note, verification: contract.verification };
+}
+/** How a run turned out, from why it stopped (`done` carries the lead's own verdict). */
+export function endOutcome(endReason, done) {
+    switch (endReason) {
+        case "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":
+            return { outcome: "partial", note: "All mailboxes were empty but the lead never sent a done message." };
+        case "max_rounds":
+            return { outcome: "partial", note: "Stopped at the round limit before the lead sent done." };
+    }
+}

package/dist/run-session.d.ts

@@ -0,0 +1,92 @@
+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";
+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;
+/** 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;
+    rounds: number;
+    endReason: EndReason;
+    /** How the work turned out; only "completed" means success. */
+    outcome: RunOutcome;
+    outcomeNote?: string;
+    verification?: string;
+    doneMessage?: {
+        subject: string;
+        body: string;
+    };
+    /** Set when the run waits for the user: the file with the questions. */
+    askReplyPath?: 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 declare class RunSession {
+    private readonly opts;
+    private readonly resume;
+    private readonly invoke;
+    private readonly say;
+    private readonly cfg;
+    private readonly runId;
+    private readonly runDir;
+    /** The project bound to this run (own memory dirs and mailboxes). */
+    private readonly project;
+    private readonly wsMode;
+    private readonly log;
+    private readonly guard;
+    private readonly state;
+    private endReason;
+    private doneMessage;
+    /** The lead's done file; it leaves the outbox only after the result and end state are stored. */
+    private pendingDoneFile;
+    private doneOutcome;
+    private doneNote;
+    private doneVerification;
+    /** Inbox mail each agent in the current batch is working on; it is marked read only after its output is routed. */
+    private readonly claims;
+    private readonly noSessionNoted;
+    /** Git worktrees of the non-lead agents in the batch being woken (empty in shared mode and for the lead). */
+    private batchSpaces;
+    /** 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;
+    private pendingAgents;
+    private pickBatch;
+    private wake;
+    /**
+     * A finished member's files go from its worktree into the repo before anyone reads its mail, so the lead
+     * sees them. When that cannot be done, nothing is applied, the member's work stays on its branch, and the lead is told.
+     */
+    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>;
+}