agent-lyceum 0.25.0 → 0.26.0

package/dist/message-store.js

@@ -15,6 +15,11 @@ export const mailDir = (runDir) => path.join(runDir, "mail");
 export class RouteJournal {
     file;
     entries = new Map();
+    byMsg = new Map();
+    byFileName = new Map();
+    assigns = new Map();
+    firstHeldSeq = new Map();
+    seqNext = 0;
     constructor(runDir) {
         this.file = path.join(mailDir(runDir), "journal.jsonl");
         let text = "";
@@ -30,27 +35,65 @@ export class RouteJournal {
             try {
                 const j = JSON.parse(line);
                 const key = `${j.source}\u0000${j.to}`;
-                if (j.t === "intent")
-                    this.entries.set(key, { source: j.source, to: j.to, msg_id: j.msg_id, file: j.file, created: j.created, delivered: false });
+                if (j.t === "intent") {
+                    this.index({
+                        source: j.source,
+                        to: j.to,
+                        msg_id: j.msg_id,
+                        file: j.file,
+                        created: j.created,
+                        delivered: false,
+                        ...(j.held === true ? { held: true } : {}),
+                        ...(j.parallel === true ? { parallel: true } : {}),
+                        ...(typeof j.from === "string" ? { from: j.from } : {}),
+                        ...(typeof j.about === "string" ? { about: j.about } : {}),
+                    });
+                }
                 else if (j.t === "delivered") {
                     const e = this.entries.get(key);
                     if (e)
                         e.delivered = true;
                 }
+                else if (j.t === "assign" && typeof j.msg_id === "string" && typeof j.slot === "string") {
+                    this.assigns.set(j.msg_id, { slot: j.slot, file: String(j.file), role: String(j.role) });
+                }
             }
             catch {
                 /* a line cut short by a crash: ignore it */
             }
         }
     }
+    /** Enter an intent in every index; `seq` is its position among the records read or appended. */
+    index(e) {
+        e.seq = this.seqNext++;
+        this.entries.set(`${e.source}\u0000${e.to}`, e);
+        this.byMsg.set(e.msg_id, e);
+        this.byFileName.set(e.file, e);
+        if (e.held && !this.firstHeldSeq.has(e.to))
+            this.firstHeldSeq.set(e.to, e.seq);
+        return e;
+    }
     get(source, to) {
         return this.entries.get(`${source}\u0000${to}`);
     }
     append(obj) {
         fs.mkdirSync(path.dirname(this.file), { recursive: true });
-        const fd = fs.openSync(this.file, "a");
+        const fd = fs.openSync(this.file, "a+");
         try {
-            fs.writeSync(fd, JSON.stringify(obj) + "\n");
+            let text = `${JSON.stringify(obj)}\n`;
+            // A crash or a short write can leave the last line without its newline; appending straight after it would glue the two into one
+            // unreadable line. The real tail is read on every append (one byte), so no cached check can go stale, even with another writer.
+            const size = fs.fstatSync(fd).size;
+            if (size > 0) {
+                const last = Buffer.alloc(1);
+                fs.readSync(fd, last, 0, 1, size - 1);
+                if (last[0] !== 0x0a)
+                    text = `\n${text}`;
+            }
+            const bytes = Buffer.from(text);
+            const written = fs.writeSync(fd, bytes);
+            if (written < bytes.length)
+                throw new Error(`Short write to ${this.file}: ${written} of ${bytes.length} bytes (disk full?). Resume the run after freeing space.`);
             fs.fsyncSync(fd);
         }
         finally {
@@ -59,9 +102,34 @@ export class RouteJournal {
     }
     intent(e) {
         this.append({ t: "intent", ...e });
-        const entry = { ...e, delivered: false };
-        this.entries.set(`${e.source}\u0000${e.to}`, entry);
-        return entry;
+        return this.index({ ...e, delivered: false });
+    }
+    /** The assigner's decision for a held mail, made durable before the file moves (spec 23.7.2). */
+    assign(a) {
+        this.append({ t: "assign", ...a });
+        this.assigns.set(a.msg_id, { slot: a.slot, file: a.file, role: a.role });
+    }
+    assigned(msgId) {
+        return this.assigns.get(msgId);
+    }
+    byFile(file) {
+        return this.byFileName.get(file);
+    }
+    /** Position of the first held intent addressed to `name`; undefined when there is none. */
+    firstHeld(name) {
+        return this.firstHeldSeq.get(name);
+    }
+    ownership(msgId) {
+        const intent = this.byMsg.get(msgId);
+        const assign = this.assigns.get(msgId)?.slot;
+        if (!intent && assign === undefined)
+            return undefined;
+        return {
+            ...(assign !== undefined ? { assign } : {}),
+            ...(intent?.from ? { from: intent.from } : {}),
+            ...(intent?.about ? { about: intent.about } : {}),
+            ...(intent ? { intent: { seq: intent.seq, to: intent.to, file: intent.file, source: intent.source, msg_id: intent.msg_id } } : {}),
+        };
     }
     delivered(source, to) {
         this.append({ t: "delivered", source, to });

package/dist/paths.d.ts

@@ -25,3 +25,8 @@ export interface ProjectPaths {
 export declare function projectPaths(home: string, project: string): ProjectPaths;
 /** True when `child` is `parent` or inside it. */
 export declare function isInside(parent: string, child: string): boolean;
+/**
+ * `p` with symlinks resolved as far as it exists: the real path of its deepest existing ancestor plus the rest. A path that does not exist
+ * yet (a directory about to be made) still compares equal to the same place reached through a symlink.
+ */
+export declare function canonicalPath(p: string): string;

package/dist/paths.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 export const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
@@ -46,5 +47,26 @@ export function projectPaths(home, project) {
 /** True when `child` is `parent` or inside it. */
 export function isInside(parent, child) {
     const rel = path.relative(parent, child);
-    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+/**
+ * `p` with symlinks resolved as far as it exists: the real path of its deepest existing ancestor plus the rest. A path that does not exist
+ * yet (a directory about to be made) still compares equal to the same place reached through a symlink.
+ */
+export function canonicalPath(p) {
+    const abs = path.resolve(p);
+    const rest = [];
+    let head = abs;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(head), ...rest);
+        }
+        catch {
+            const up = path.dirname(head);
+            if (up === head)
+                return abs;
+            rest.unshift(path.basename(head));
+            head = up;
+        }
+    }
 }

package/dist/policy.d.ts

@@ -44,6 +44,7 @@ export declare const scratchCwd: (workDir: string) => string;
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export declare function repoDirFor(project: ResolvedProject, agent: string): string;
 export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;
+export declare function osSandboxAvailable(): boolean;
 /** Test seam: pretend the OS sandbox is (un)available; `undefined` re-probes the host. */
 export declare function setOsSandboxForTest(available: boolean | undefined): void;
 export declare function enforcementFor(project: ResolvedProject, agent: ResolvedAgent): AgentEnforcement;

package/dist/policy.js

@@ -136,13 +136,13 @@ export function writePolicy(project, agent) {
         deny.push(path.join(ws.root, ".git"), ...["commondir", "config.worktree", "gitdir"].map((f) => path.join(ws.gitDir, f)));
     return {
         allowDirs,
-        readDirs: [...(shared && !mayWriteShared ? [shared] : []), ...(isLead ? [] : [recordsDir(project)])],
+        readDirs: [...(shared && !mayWriteShared ? [shared] : []), ...(isLead ? [] : [recordsDir(project)]), ...Object.values(agent.sharedMemory ?? {})],
         allowFiles,
         deny: [...new Set(deny)],
     };
 }
 let sandboxProbe;
-function osSandboxAvailable() {
+export function osSandboxAvailable() {
     if (sandboxProbe !== undefined)
         return sandboxProbe;
     if (process.platform === "darwin")

package/dist/prompt.d.ts

@@ -1,6 +1,8 @@
 import type { ResolvedAgent, ResolvedProject } from "./config.js";
 import type { Message } from "./mailbox.js";
 import type { Layer, MemoryFile, MissingPath, ProjectChanges } from "./memory-tidy.js";
+/** The lead's system prompt gets this at its very end when same-role instances are possible in the run (spec 23.12). No trailing newline. */
+export declare const PARALLEL_SECTION: (n: number) => string;
 export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_LIMIT: number;
 export declare const HANDOFF_LIMIT: number;

package/dist/prompt.js

@@ -2,13 +2,28 @@ import fs from "node:fs";
 import { cutUtf8, readFileCapped } from "./fs-util.js";
 import path from "node:path";
 import { REQUIRED_SECTIONS } from "./format.js";
+import { senderLabel, slotName } from "./instances.js";
 import { buildRecordsView, RECORDS_BUDGET } from "./records.js";
 import { commonFile, memoryDirs, outboxDir, recordsKindDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
 function memoryLabel(agent, dir) {
     if (dir === agent.memory.task)
         return "task (this task only, isolated)";
-    return dir === agent.memory.global ? "global (all projects)" : "project (all tasks of this project)";
+    const shared = agent.sharedMemory && Object.values(agent.sharedMemory).includes(dir);
+    const instance1 = agent.instance ? slotName(agent.instance.role, 1) : "";
+    const kind = dir === (agent.memory.global ?? agent.sharedMemory?.global) ? "global (all projects" : "project (all tasks of this project";
+    return shared ? `${kind}, read-only for you: ${instance1} maintains it)` : `${kind})`;
 }
+/** The lead's system prompt gets this at its very end when same-role instances are possible in the run (spec 23.12). No trailing newline. */
+export const PARALLEL_SECTION = (n) => [
+    "## Parallel tasks",
+    `A member can work on up to ${n} tasks at the same time, each in its own instance with its own worktree. To use this, send each independent task as its own new \`task\` (not a reply, no \`reply_to\`) with the frontmatter line \`parallel: true\`. Only your own mail can do this. Instance 1 keeps the member's name; the others are named \`<member>--2\`, \`<member>--3\`, and their mail reaches you from those names.`,
+    "- Mark tasks parallel only when they are independent of each other and change different files. Before you send them, list in each task's `## Scope` the files it will touch; if two lists overlap, do not mark them parallel.",
+    "- Never run in parallel work that changes shared components, types, routes, configuration or design tokens: send that first, without the flag, and send the dependent tasks after it is integrated. Changes to the same file are not merged: the later one is blocked and comes back to you as a failure.",
+    "- Revisions go back to the instance that did the work: reply to its mail (`reply_to`). An instance whose work is blocked takes no new task, also not one addressed to it by name, until that work is in the repo; to redo it, reply to the failure about it.",
+    "- Without `parallel: true`, mail goes to the member itself, one task at a time.",
+    "- When rate limits hit, fewer instances may start; waiting tasks run when an instance is free.",
+    "- After parallel work is back, have one member type-check and test the combined result before you report `done`.",
+].join("\n");
 export const COMMON_LIMIT = 8 * 1024;
 export const MEMORY_INDEX_LIMIT = 4 * 1024;
 export const HANDOFF_LIMIT = COMMON_LIMIT;
@@ -81,12 +96,22 @@ export function buildSystemPrompt(project, agent) {
     if (project.solo)
         return buildSoloSystemPrompt(project, agent);
     const outbox = outboxDir(project, agent.name);
-    const mates = Object.keys(project.agents).filter((n) => n !== agent.name);
+    // Instances 2 and up are not listed (the lead is told their names separately), and an instance does not list its own role's other instances.
+    const mates = Object.keys(project.agents).filter((n) => n !== agent.name && (project.agents[n]?.instance?.k ?? 1) < 2 && (!agent.instance || project.agents[n]?.instance?.role !== agent.instance.role));
     const recipients = agent.canMessage === "all" ? mates : agent.canMessage.filter((n) => project.agents[n] && n !== agent.name);
     const isLead = agent.name === project.lead;
     const lines = [];
     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]
+    lines.push(agent.instance && agent.instance.k >= 2
+        ? `You are **${agent.name}**, instance ${agent.instance.k} of **${agent.instance.role}** in the team "${project.name}". Other instances of ${agent.instance.role} may be working on other tasks at the same time, each in its own worktree. You work in the repository \`${repoDirFor(project, agent.name)}\`.`
+        : `You are **${agent.name}**, a member of the team "${project.name}". You work in the repository \`${repoDirFor(project, agent.name)}\`.`, ...(agent.instance?.k === 1
+        ? [
+            `Other instances of you${(() => {
+                const names = Object.values(project.agents).filter((a) => a.instance?.role === agent.name && a.instance.k >= 2).map((a) => a.name);
+                return names.length ? ` (${names.join(", ")})` : "";
+            })()} may work in parallel; only you write your global/project memory.`,
+        ]
+        : []), ...(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.`,
         ]
@@ -125,14 +150,17 @@ export function buildSystemPrompt(project, agent) {
         ]
         : []), ...(isLead && sharedDir(project) ? handoffRule(sharedDir(project)) : []), "", "## Memory");
     const mems = memoryDirs(agent);
+    const sharedMems = Object.values(agent.sharedMemory ?? {});
     if (mems.length === 0)
         lines.push("You have no long-term memory directory.");
-    for (const m of mems) {
+    for (const m of [...sharedMems, ...mems]) {
         const label = memoryLabel(agent, m);
         lines.push(`- ${label}: \`${m}\``);
     }
     if (mems.length) {
-        lines.push("Keep a `MEMORY.md` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt", "on every wake-up; read other memory files on demand; you can write only inside these directories.", "Put anything specific to the current task (decisions, progress, findings, branch names) in the **task** memory: it is private to this task and starts empty for every new task.", "Also record approaches you considered but rejected, with the reason, so they can be revisited or reversed later.", "Use the global/project memory only for durable lessons that stay true across tasks; never record task-specific details there.");
+        lines.push("Keep a `MEMORY.md` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt", "on every wake-up; read other memory files on demand; you can write only inside these directories.", "Put anything specific to the current task (decisions, progress, findings, branch names) in the **task** memory: it is private to this task and starts empty for every new task.", "Also record approaches you considered but rejected, with the reason, so they can be revisited or reversed later.", ...(sharedMems.length
+            ? ["You cannot write the shared memory: put lessons worth keeping in your reply to the lead."]
+            : ["Use the global/project memory only for durable lessons that stay true across tasks; never record task-specific details there."]));
     }
     lines.push("", "## Rules");
     lines.push("- Never edit any `AGENT.md`, `COMMON.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`" +
@@ -141,7 +169,8 @@ export function buildSystemPrompt(project, agent) {
             `- You also keep two kinds of durable records for every future run of this project, one Markdown file per entry: decisions in \`${recordsKindDir(project, "decisions")}/\` (what was decided and why) and lessons in \`${recordsKindDir(project, "lessons")}/\` (heuristics and pitfalls that stay true). The file name without \`.md\` is the entry id (lowercase letters, digits, \`-\`). Each file starts with YAML frontmatter between \`---\` lines: \`status: active|superseded\`, \`date: YYYY-MM-DD\`, \`title: <one line>\`, optionally \`run: <run id>\` and \`supersedes: [<ids of entries of the same kind>]\`; the body is the decision or lesson and its reason. Prompts show only effective-active entries (\`status: active\` and not named in another entry's \`supersedes\`), newest first, up to ${CONTEXT_LIMIT / 1024} KB per kind, and list what does not fit as one line each. When an entry becomes outdated, mark it \`status: superseded\` or name it in a new entry's \`supersedes\`. Add or update entries before you send \`done\`.`,
         ]
         : []), PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
-    return lines.join("\n");
+    const text = lines.join("\n");
+    return isLead && project.run?.instances ? `${text}\n\n${PARALLEL_SECTION(project.run.instances.max)}` : text;
 }
 /** Messages one wake-up handles: the oldest one, or a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so the agent decides once on all of it; the lead takes any such run, other agents only same-thread ones. */
 export function pickMessages(project, agent, queue) {
@@ -188,7 +217,7 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff
             parts.push(`\n[handoff index truncated at ${HANDOFF_LIMIT} bytes — the lead should condense it.]`);
         parts.push("The other files in that folder are there to read on demand.");
     }
-    for (const dir of memoryDirs(agent)) {
+    for (const dir of [...Object.values(agent.sharedMemory ?? {}), ...memoryDirs(agent)]) {
         const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
         const label = memoryLabel(agent, dir).split(" ")[0];
         parts.push("", `# Your ${label} memory index (${dir}/MEMORY.md)`);
@@ -216,12 +245,12 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff
         const body = shown.length === raw.length
             ? m.body
             : `${shown.toString("utf8")}\n[agent-lyceum: this message was cut at ${shown.length} of ${raw.length} bytes; read the whole message in \`${m.file}\` (it moves to \`read/\` in the same folder after this wake-up)]`;
-        parts.push(`id: ${m.meta.id}`, `from: ${m.meta.from}`, `type: ${m.meta.type}`, `thread: ${m.meta.thread}`, `subject: ${m.meta.subject}`, "", body);
+        parts.push(`id: ${m.meta.id}`, `from: ${senderLabel(m.meta.from, project.agents)}`, `type: ${m.meta.type}`, `thread: ${m.meta.thread}`, `subject: ${m.meta.subject}`, "", body);
     });
     if (queued.length) {
         parts.push("", "# Queued messages (not handled in this wake-up; each gets its own wake-up later, titles only)");
         for (const m of queued)
-            parts.push(`- from ${m.meta.from} [${m.meta.type}] "${m.meta.subject}" -> ${m.file}`);
+            parts.push(`- from ${senderLabel(m.meta.from, project.agents)} [${m.meta.type}] "${m.meta.subject}" -> ${m.file}`);
     }
     return parts.join("\n");
 }

package/dist/run-session.d.ts

@@ -63,6 +63,11 @@ export interface RunOptions {
     log?: (line: string) => void;
     /** The wait between retries of a model with a fallback chain; tests pass one that does not wait. Default: a timer cut short by `signal`. */
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Containment check for an instance (spec 23.11 D-17): returns why instance `k` of `role` must not be opened (it could write the role's
+     * shared memory), or undefined. Asked before activation, after an instance is created and when a run is resumed. Tests inject one.
+     */
+    instanceCheck?: (role: string, k: number) => string | undefined;
 }
 export declare class RunSession {
     private readonly opts;
@@ -74,9 +79,21 @@ export declare class RunSession {
     private readonly cfg;
     private readonly runId;
     private readonly runDir;
-    /** The project bound to this run (own memory dirs and mailboxes). */
-    private readonly project;
+    /** The project bound to this run (own memory dirs and mailboxes). Bound again when the run gets instances (spec 23.6). */
+    private project;
+    /** The project as configured (solo-narrowed), before it is bound to this run. */
+    private readonly base;
+    private readonly layout;
+    /** Roles that get no new instance in this process: a check after an instance was created found a conflict. */
+    private readonly noMoreInstances;
+    private readonly heldLogged;
+    private readonly ignoredNoted;
+    /** Held mail the assigner left in `pending/` this round (read by the stall check). */
+    private waiting;
     private readonly wsMode;
+    /** D-17: the paths an instance would get against the shared memory of its role (writes nothing). */
+    private readonly containment;
+    private readonly instanceCheck;
     private readonly log;
     private readonly guard;
     private readonly state;
@@ -110,6 +127,20 @@ export declare class RunSession {
     private saveState;
     private journal;
     private note;
+    /** Bind the project to this run again, after its slot table changed. */
+    private rebind;
+    /** What the router needs to hold and place mail for roles with several instances (spec 23.7.1). */
+    private routing;
+    /** Make a new instance durable and give it its folders; false (and the role gets no more instances in this process) when a check refuses it. */
+    private openInstance;
+    /** The one round of placing held mail, at the top of the loop (spec 23.7.2). Leaves what it could not place in `this.waiting`. */
+    private assignHeld;
+    private assignRole;
+    /**
+     * The run is about to end idle but mail is still held (spec D-16). Only a cooldown in the way: wait for it (cut short by a cancel) and
+     * return true to go round again. Otherwise tell the lead once per set of waiting mails; true when that mail is new (the lead has work).
+     */
+    private stallHeld;
     private pendingAgents;
     private pickBatch;
     private wake;