agent-lyceum 0.4.14 → 0.5.0

package/dist/mailbox.js

@@ -6,6 +6,7 @@ import { formatWarning, missingSections, parseSteps } from "./format.js";
 import { atomicWrite } from "./fs-util.js";
 import { deterministicId, fault, RouteJournal, sourceIdOf } from "./message-store.js";
 import { inboxDir, outboxDir } from "./policy.js";
+import { must } from "./assert.js";
 export { atomicWrite };
 export const MESSAGE_TYPES = ["task", "reply", "failure", "done"];
 export function newId() {
@@ -25,17 +26,17 @@ export function parseRaw(text) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!m)
         throw new Error("missing frontmatter (--- ... ---)");
-    const data = YAML.parse(m[1]);
+    const data = YAML.parse(m[1] ?? "");
     if (!data || typeof data !== "object" || Array.isArray(data))
         throw new Error("frontmatter is not a mapping");
-    return { data: data, body: m[2].trim() };
+    return { data: data, body: (m[2] ?? "").trim() };
 }
 export function ensureProjectDirs(project) {
     fs.mkdirSync(path.join(project.paths.shared, "common"), { recursive: true });
     for (const name of Object.keys(project.agents)) {
         fs.mkdirSync(path.join(inboxDir(project, name), "read"), { recursive: true });
         fs.mkdirSync(path.join(outboxDir(project, name), "rejected"), { recursive: true });
-        const a = project.agents[name];
+        const a = must(project.agents[name], `agent ${name}`);
         for (const m of [a.memory.global, a.memory.project, a.memory.task])
             if (m)
                 fs.mkdirSync(m, { recursive: true });
@@ -109,15 +110,19 @@ export function readMessage(file) {
     const meta = data;
     return { meta, body, file };
 }
-export function listUnread(project, agent) {
+/** Paths of the unread messages in an agent's inbox, oldest name first. Does not open them. */
+export function unreadFiles(project, agent) {
     const dir = inboxDir(project, agent);
     if (!fs.existsSync(dir))
         return [];
-    const files = fs
+    return fs
         .readdirSync(dir, { withFileTypes: true })
         .filter((e) => e.isFile() && e.name.endsWith(".md") && !e.name.startsWith("."))
         .map((e) => path.join(dir, e.name))
         .sort();
+}
+export function listUnread(project, agent) {
+    const files = unreadFiles(project, agent);
     const out = [];
     for (const f of files) {
         try {

package/dist/policy.js

@@ -1,6 +1,6 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { findOnPath } from "./fs-util.js";
 import { globStaticPrefix } from "./paths.js";
 export function commonFile(project) {
     return path.join(project.paths.shared, "common", "COMMON.md");
@@ -17,7 +17,7 @@ export function repoInstructionFiles(project) {
 export function memoryDirs(a) {
     return [a.memory.global, a.memory.project, a.memory.task].filter((x) => !!x);
 }
-const RUN_ENTRIES = ["state.json", "log.jsonl", "result.md", "task.md", "snapshots", "agents", "mail"];
+const RUN_ENTRIES = ["state.json", "log.jsonl", "log.1.jsonl", "result.md", "task.md", "snapshots", "violations", "agents", "mail"];
 const MAIL_ENTRIES = ["inbox", "claims", "attempts", "journal.jsonl"];
 function entries(dir) {
     try {
@@ -101,7 +101,7 @@ function osSandboxAvailable() {
     if (process.platform === "darwin")
         sandboxProbe = true;
     else if (process.platform === "linux")
-        sandboxProbe = spawnSync("which", ["bwrap"]).status === 0;
+        sandboxProbe = findOnPath("bwrap");
     else
         sandboxProbe = false;
     return sandboxProbe;

package/dist/process-runner.js

@@ -125,8 +125,7 @@ export function runInvocation(inv, opts) {
                 return;
             let text = partial + chunk.toString("utf8");
             partial = "";
-            let nl;
-            while ((nl = text.indexOf("\n")) >= 0) {
+            for (let nl = text.indexOf("\n"); nl >= 0; nl = text.indexOf("\n")) {
                 const line = text.slice(0, nl).replace(/\r$/, "");
                 text = text.slice(nl + 1);
                 if (skipping)

package/dist/project-lock.d.ts

@@ -3,7 +3,7 @@ export interface LockInfo {
     token: string;
     hostname: string;
     pid: number;
-    /** `ps` start time of `pid`, to tell the holder from a different process that reused the pid. */
+    /** Start time of `pid` (see `pidStartFrom`), to tell the holder from a different process that reused the pid. */
     pid_started?: string;
     run_id: string;
     acquired_at: string;
@@ -18,6 +18,15 @@ export interface ProjectLease {
 export interface LockOptions {
     heartbeatMs?: number;
 }
+/** Field 22 (starttime, in clock ticks) of a /proc/<pid>/stat line. The command name (field 2) may contain spaces and ")". */
+export declare function parseProcStat(text: string): string | undefined;
+export interface PidStartIo {
+    platform: NodeJS.Platform;
+    readFile(p: string): string | undefined;
+    ps(pid: number): string | undefined;
+}
+/** A start time that identifies one process: `proc:<ticks>` on Linux, the `ps` text elsewhere or when /proc cannot be read. */
+export declare function pidStartFrom(pid: number, io: PidStartIo): string | undefined;
 /** The lock of a project (`root` = the project's home directory), if one is held and readable. */
 export declare function inspectProjectLock(root: string): LockInfo | undefined;
 /**

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.js

@@ -32,7 +32,7 @@ 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
         ? `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.`

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,26 @@
+/** 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 "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,82 @@
+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;
+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 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);
+    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;
+    /** On resume: sort out what the interrupted process left behind before anything is woken. */
+    private recover;
+    run(): Promise<RunSummary>;
+}