agent-lyceum 0.25.1 → 0.27.0

package/dist/prompt.js

@@ -2,13 +2,45 @@ 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 { modelForTier } from "./tiers.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})`;
 }
+/** Lead-only rules that keep the number of wake-ups down; placed after the progress-tracking block. */
+export const WAKE_ECONOMY_SECTION = [
+    "## Keeping wake-ups few",
+    "Every wake-up re-reads your whole context (prompt, memory, mail), so the number of wake-ups, yours and your teammates', is the main cost of a run.",
+    "- Send all work that is independent of each other in the same wake-up (for example the implementation and the matching docs), each task naming its reviewer, instead of one task per wake-up.",
+    "- When a reply arrives while other work you sent is still out and the reply needs nothing from you yet, send no mail: note it in your task memory and end the wake-up. Decide the next step once, when the rest is back; replies waiting together are handed to you in one wake-up.",
+    "- Skip the QA layer (the verification role and its reviewer) for a small fix: a change of a few lines that has a reproduction test which failed before and passes after, and an approving code review. Send QA for large changes, changes across modules, and changes to user-visible behaviour.",
+    "- Use the most capable (most expensive) model only at three moments: before the plan is final, when the same error shows up a second time, and before you send `done`. In other rounds prefer teammates on cheaper models; read-only search work suits the cheapest one.",
+];
+/** 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");
+/** The lead's system prompt ends with this when a member can run a task on a cheaper model (spec 24.10); `members` = [name, model of low, mid, high]. No trailing newline. */
+export const TIER_SECTION = (members) => [
+    "## Task tiers",
+    "Some members can run a task on a cheaper model than their own. Add the frontmatter line `tier: low`, `tier: mid` or `tier: high` to a `task` you send them; without it they use their own model. Pick by difficulty: `low` for mechanical work with an exact spec (renames, a one-line fix, running a given command), `mid` for routine changes in one module, `high` (or no tier) for design, debugging, reviews and anything unclear. A tier lasts for that one task: replies and later mail on the thread run on the member's own model, so put `tier` again on each follow-up task. Each model keeps its own session, so a member that resumes sessions does not see what it did on another model; say in the task what it needs. If a tiered task comes back poor, send it again with a higher tier.",
+    "Members and the models each tier uses:",
+    ...members.map((m) => `- ${m.name}: low ${m.low}, mid ${m.mid}, high ${m.high}`),
+].join("\n");
 export const COMMON_LIMIT = 8 * 1024;
 export const MEMORY_INDEX_LIMIT = 4 * 1024;
 export const HANDOFF_LIMIT = COMMON_LIMIT;
@@ -81,12 +113,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.`,
         ]
@@ -123,16 +165,19 @@ export function buildSystemPrompt(project, agent) {
             "Your final `done` mail must also include the full `## Steps` checklist. Tick only steps that were actually done and verified; leave undone ones",
             "(e.g. build, app start, commit) unticked and say so in the mail instead of reporting them as finished.",
         ]
-        : []), ...(isLead && sharedDir(project) ? handoffRule(sharedDir(project)) : []), "", "## Memory");
+        : []), ...(isLead ? ["", ...WAKE_ECONOMY_SECTION] : []), ...(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 +186,18 @@ 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");
+    let text = lines.join("\n");
+    if (isLead && project.run?.instances)
+        text = `${text}\n\n${PARALLEL_SECTION(project.run.instances.max)}`;
+    if (isLead) {
+        const members = Object.values(project.agents)
+            .filter((a) => a.name !== project.lead && (!a.instance || a.instance.k === 1) && (a.tiers?.length ?? 0) >= 2)
+            .sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0))
+            .map((a) => ({ name: a.name, low: modelForTier(a.tiers, "low"), mid: modelForTier(a.tiers, "mid"), high: modelForTier(a.tiers, "high") }));
+        if (members.length)
+            text = `${text}\n\n${TIER_SECTION(members)}`;
+    }
+    return 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 +244,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 +272,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,22 @@ export declare class RunSession {
     private saveState;
     private journal;
     private note;
+    /** Spec 24.5.2: log every tier that was dropped; tell the sender once per reason (`no-tiers` is log-only). */
+    private noteTierIgnored;
+    /** 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;