agent-lyceum 0.5.0 → 0.6.0

package/dist/prompt.js

@@ -34,13 +34,31 @@ export function buildSystemPrompt(project, agent) {
         ? [
             `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-outcome.js

@@ -16,6 +16,8 @@ export function endOutcome(endReason, 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":

package/dist/run-session.d.ts

@@ -8,6 +8,8 @@ export type { ActiveWake, EndReason, RunState, SentTopic, WakeRecord, WakeTopic
 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;
@@ -21,6 +23,8 @@ export interface RunSummary {
         subject: string;
         body: string;
     };
+    /** Set when the run waits for the user: the file with the questions. */
+    askReplyPath?: string;
 }
 export interface RunOptions {
     project: ResolvedProject;
@@ -63,6 +67,8 @@ export declare class RunSession {
     /** 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;
@@ -76,6 +82,10 @@ export declare class RunSession {
     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>;

package/dist/run-session.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { realInvoker } from "./adapters/index.js";
 import { briefOf, doneContract, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
+import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, writeAskReply } from "./ask-reply.js";
 import { deliver, deliverOnce, ensureProjectDirs, finishDone, listUnread, rejectDone, routeOutboxes, unreadFiles } from "./mailbox.js";
 import { abandonClaim, attemptLogDir, sourceIdOf, beginAttempt, claimMessages, commitClaim, finishAttempt, markOutputReady, parkOutbox, recoverRunMail, RouteJournal } from "./message-store.js";
 import { isInside } from "./paths.js";
@@ -19,6 +20,8 @@ export { newRunId };
 export const RESULT_FILE = "result.md";
 /** How many times a non-conforming `done` goes back to the lead before it is accepted as `partial`. */
 export const MAX_DONE_REJECTIONS = 2;
+/** How many times a malformed `ask` goes back to its sender before the lead is told instead. */
+export const MAX_ASK_REJECTIONS = 2;
 /** Prompt for a repeat attempt: the earlier one failed and may have changed things already. */
 function retryPrompt(prompt, error) {
     return `${prompt}\n\n# Retry notice\nYour previous attempt at this wake-up failed${error ? ` (${error})` : ""} after possibly changing files already. Its mail was discarded. Check the current state of the repository before redoing the work, and send the mail again.`;
@@ -53,6 +56,8 @@ export class RunSession {
     attempts = new Map();
     constructor(opts) {
         const { task, resume, runDir } = opts;
+        if (resume?.end_reason === "waiting")
+            RunSession.assertAnswered(runDir, resume.run_id);
         if (!task && !resume)
             throw new Error("runTeam needs a task or a run to resume");
         const invoke = opts.invoker ?? realInvoker;
@@ -129,6 +134,16 @@ export class RunSession {
         this.guard = guard;
         this.state = state;
     }
+    /** A waiting run only continues once every unanswered question has a valid answer. */
+    static assertAnswered(runDir, runId) {
+        const reply = readAskReply(runDir);
+        if (!reply)
+            return;
+        const check = checkAnswers(reply);
+        if (!isComplete(check)) {
+            throw new Error(`Run ${runId} is still waiting for answers in ${askReplyPath(runDir)}:\n${describeCheck(check).map((l) => `  ${l}`).join("\n")}`);
+        }
+    }
     saveState() {
         saveRunState(this.runDir, this.state);
     }
@@ -354,6 +369,7 @@ export class RunSession {
                 contract = undefined;
             }
         }
+        const askAccepted = this.handleAsks(route);
         for (const d of route.delivered)
             log("route", d);
         const handedOff = (from, t) => {
@@ -402,6 +418,10 @@ export class RunSession {
             this.endReason = "done";
             return;
         }
+        if (askAccepted) {
+            this.endReason = "waiting";
+            return;
+        }
         const leadIdx = batch.findIndex((a) => a.name === project.lead);
         const leadResult = leadIdx >= 0 ? results[leadIdx] : undefined;
         if (leadResult && !leadResult.ok && !leadResult.cancelled) {
@@ -409,9 +429,86 @@ export class RunSession {
             return;
         }
     }
+    /** The user answered: send each asker its answers as a `reply`, then mark them delivered. Safe to repeat after a crash. */
+    deliverAnswers() {
+        const { runDir, project, log } = this;
+        const reply = readAskReply(runDir);
+        if (!reply)
+            return;
+        const ids = reply.questions.filter((q) => !q.delivered).map((q) => q.id).join(",");
+        for (const asker of askersWithAnswers(reply)) {
+            deliverOnce(project, this.journal(), `ask-answer:${ids}:${asker}`, {
+                from: "user",
+                to: asker,
+                type: "reply",
+                subject: "Answers to your questions",
+                body: renderAnswers(reply, asker),
+            });
+        }
+        writeAskReply(runDir, markDelivered(reply));
+        log("ask-answered", { questions: ids });
+    }
+    /** 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. */
+    handleAsks(route) {
+        const { say, runDir, project, log, state } = this;
+        if (route.asks.length === 0)
+            return false;
+        let reply = readAskReply(runDir);
+        const accepted = [];
+        for (const a of route.asks) {
+            const parsed = parseAskBody(a.body);
+            const added = parsed.ok ? addBatch(reply, a.from, state.rounds, parsed.questions) : parsed;
+            if (!added.ok) {
+                const n = (state.ask_rejections?.[a.from] ?? 0) + 1;
+                state.ask_rejections = { ...state.ask_rejections, [a.from]: n };
+                rejectDone(a.file);
+                const reason = added.error;
+                say(`  ask from ${a.from} rejected: ${reason}`);
+                log("ask-rejected", { from: a.from, reason, count: n });
+                if (n <= MAX_ASK_REJECTIONS) {
+                    deliverOnce(project, this.journal(), `ask-reject:${a.source}`, {
+                        from: "dispatcher",
+                        to: a.from,
+                        type: "failure",
+                        subject: "Your ask was not accepted",
+                        body: `Your \`ask\` was not accepted: ${reason}.\n\nSend it again with this shape (at most 10 questions; \`options\` and \`suggested\` are optional):\n\n<ask>\n  <question id="q1">\n    <text>Question?</text>\n    <options><option>a</option><option>b</option></options>\n    <suggested reason="why">a</suggested>\n  </question>\n</ask>\n\n(Reminder ${n} of ${MAX_ASK_REJECTIONS}.)`,
+                    });
+                }
+                else {
+                    deliverOnce(project, this.journal(), `ask-reject:${a.source}`, {
+                        from: "dispatcher",
+                        to: project.lead,
+                        type: "failure",
+                        subject: `${a.from}'s ask was rejected ${n} times`,
+                        body: `${a.from} sent a malformed \`ask\` rejected ${n} times (last problem: ${reason}). It was dropped. Decide without asking the user, or send the question yourself in the correct format.`,
+                    });
+                }
+                continue;
+            }
+            reply = added.reply;
+            accepted.push(a.file);
+        }
+        if (!accepted.length || !reply)
+            return false;
+        if (route.done) {
+            for (const f of accepted)
+                finishDone(f);
+            this.note("An ask was ignored because the lead also sent done in the same round.");
+            return false;
+        }
+        // Questions are stored first, the outbox file moves second: a crash in between re-routes the same ask, and addBatch skips it.
+        writeAskReply(runDir, reply);
+        for (const f of accepted)
+            finishDone(f);
+        log("ask", { questions: reply.questions.filter((q) => !q.delivered).map((q) => q.id) });
+        say(`  waiting for your answers: ${askReplyPath(runDir)}`);
+        return true;
+    }
     /** On resume: sort out what the interrupted process left behind before anything is woken. */
     recover() {
         const { say, runId, runDir, project, wsMode, log } = this;
+        if (this.resume?.end_reason === "waiting")
+            this.deliverAnswers();
         const rec = recoverRunMail(runDir, { outboxOf: (agent) => outboxDir(project, agent) });
         for (const i of rec.interrupted) {
             this.note(`${i.attempt.agent} attempt ${i.attempt.n} was interrupted${i.parked.length ? `; ${i.parked.length} output file(s) set aside in ${path.join("mail", "attempts", i.attempt.id, "outbox")}` : ""}. ` +
@@ -500,6 +597,6 @@ export class RunSession {
         this.saveState();
         if (this.pendingDoneFile)
             finishDone(this.pendingDoneFile);
-        return { runId, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, doneMessage: this.doneMessage };
+        return { runId, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, doneMessage: this.doneMessage, askReplyPath: endReason === "waiting" ? askReplyPath(runDir) : undefined };
     }
 }

package/dist/run-store.d.ts

@@ -3,7 +3,7 @@ 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 EndReason = "done" | "idle" | "max_rounds" | "lead_failed" | "cancelled" | "waiting";
 export type MailLayout = "run" | "legacy";
 export interface WakeTopic {
     from: string;
@@ -56,6 +56,8 @@ export interface RunState {
     verification?: string;
     /** How many `done` mails were sent back because they broke the completion contract. */
     done_rejections?: number;
+    /** How many malformed `ask` mails each agent had sent back (the limit is MAX_ASK_REJECTIONS). */
+    ask_rejections?: Record<string, number>;
     /** Recovery remarks (interrupted attempts whose side effects may have happened). */
     notes?: string[];
     /** "worktree": non-lead agents work in their own git worktrees. */

package/dist/run-store.js

@@ -23,12 +23,13 @@ const WireState = z
     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(),
+    end_reason: z.enum(["done", "idle", "max_rounds", "lead_failed", "cancelled", "waiting"]).optional(),
+    outcome: z.enum(["completed", "partial", "blocked", "failed", "waiting", "cancelled"]).optional(),
     outcome_note: z.string().optional(),
     verification: z.string().optional(),
     done_rejections: nonNeg.optional(),
     notes: z.array(z.string()).optional(),
+    ask_rejections: z.record(z.string(), nonNeg).optional(),
     sessions: z.record(z.string(), z.string()).optional(),
     output_tokens: nonNeg.optional(),
     last_wake: z.record(z.string(), z.any()).optional(),
@@ -115,5 +116,5 @@ export function outcomeOf(s) {
         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 };
+    return { outcome: s.end_reason === "lead_failed" ? "failed" : s.end_reason === "cancelled" ? "cancelled" : s.end_reason === "waiting" ? "waiting" : "partial", verified: false };
 }

package/dist/schema.d.ts

@@ -30,6 +30,7 @@ export declare const AgentPartial: z.ZodObject<{
     resume: z.ZodOptional<z.ZodBoolean>;
     can_message: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>>;
     can_edit_agent_md: z.ZodOptional<z.ZodBoolean>;
+    can_ask_user: z.ZodOptional<z.ZodBoolean>;
     owns: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type AgentPartialT = z.infer<typeof AgentPartial>;
@@ -69,6 +70,7 @@ export declare const GlobalConfig: z.ZodObject<{
         resume: z.ZodOptional<z.ZodBoolean>;
         can_message: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>>;
         can_edit_agent_md: z.ZodOptional<z.ZodBoolean>;
+        can_ask_user: z.ZodOptional<z.ZodBoolean>;
         owns: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
@@ -112,6 +114,7 @@ export declare const ProjectConfig: z.ZodObject<{
         resume: z.ZodOptional<z.ZodBoolean>;
         can_message: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>>;
         can_edit_agent_md: z.ZodOptional<z.ZodBoolean>;
+        can_ask_user: z.ZodOptional<z.ZodBoolean>;
         owns: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
@@ -128,6 +131,6 @@ export interface DispatcherSettings {
 }
 export declare const DISPATCHER_DEFAULTS: DispatcherSettings;
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */
-export declare const RUN_OUTCOMES: readonly ["completed", "partial", "blocked", "failed", "cancelled"];
+export declare const RUN_OUTCOMES: readonly ["completed", "partial", "blocked", "failed", "waiting", "cancelled"];
 export type RunOutcome = (typeof RUN_OUTCOMES)[number];
-export declare function exitCodeForOutcome(outcome: RunOutcome): 0 | 1 | 2 | 130;
+export declare function exitCodeForOutcome(outcome: RunOutcome): 0 | 1 | 2 | 3 | 130;

package/dist/schema.js

@@ -34,6 +34,7 @@ export const AgentPartial = z
     resume: z.boolean().optional(),
     can_message: z.union([z.literal("all"), z.array(z.string())]).optional(),
     can_edit_agent_md: z.boolean().optional(),
+    can_ask_user: z.boolean().optional(),
     owns: z.array(z.string()).optional(),
 })
     .strict();
@@ -71,13 +72,15 @@ export const DISPATCHER_DEFAULTS = {
     log_max_bytes: 8 * 1024 * 1024,
 };
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */
-export const RUN_OUTCOMES = ["completed", "partial", "blocked", "failed", "cancelled"];
+export const RUN_OUTCOMES = ["completed", "partial", "blocked", "failed", "waiting", "cancelled"];
 export function exitCodeForOutcome(outcome) {
     switch (outcome) {
         case "completed":
             return 0;
         case "failed":
             return 1;
+        case "waiting":
+            return 3;
         case "cancelled":
             return 130;
         default:

package/dist/status.d.ts

@@ -44,7 +44,7 @@ export interface RunReport {
     run_id: string;
     dir: string;
     /** running: its dispatcher is alive; interrupted: it died mid-run; ended: it stopped (see end_reason). */
-    state: "running" | "interrupted" | "ended";
+    state: "running" | "interrupted" | "ended" | "waiting";
     live: boolean;
     end_reason?: EndReason;
     outcome?: RunOutcome;
@@ -83,6 +83,12 @@ export interface RunReport {
         ok: boolean;
         error?: string;
     }>;
+    /** Present while the run waits for the user: the file to fill in and how many questions are still open. */
+    ask?: {
+        path: string;
+        total: number;
+        unanswered: number;
+    };
 }
 export interface AgentReport {
     name: string;
@@ -104,6 +110,8 @@ export interface StatusReport {
     };
     agents: AgentReport[];
     run?: RunReport;
+    /** Hints that a `memory tidy` might help. Only a suggestion; nothing runs it. */
+    memory_advice?: string[];
 }
 export interface TaskListReport {
     schema_version: 1;

package/dist/status.js

@@ -1,8 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
+import { askReplyPath, readAskReply } from "./ask-reply.js";
 import { RESULT_FILE } from "./dispatcher.js";
 import { bindRunProject, loadRunState, outcomeOf } from "./run-store.js";
 import { listUnread } from "./mailbox.js";
+import { tidyAdvice } from "./memory-tidy.js";
 import { inspectProjectLock, lockHolderAlive } from "./project-lock.js";
 export function latestRun(project) {
     const root = project.paths.runs;
@@ -76,8 +78,10 @@ function alive(pid) {
         return e.code === "EPERM";
     }
 }
-const OUTCOME_ZH = { completed: "完成", partial: "部分完成", blocked: "受阻", failed: "失敗", cancelled: "已取消" };
+const OUTCOME_ZH = { completed: "完成", partial: "部分完成", blocked: "受阻", failed: "失敗", waiting: "等待回答", cancelled: "已取消" };
 export function runStateLabel(s, live = alive(s.pid)) {
+    if (s.end_reason === "waiting")
+        return "等待回答";
     if (s.end_reason) {
         const o = outcomeOf(s);
         // Runs from before outcomes existed: keep what they recorded, but never present it as a checked success.
@@ -155,10 +159,23 @@ export function buildRunReport(run, project, opts = {}) {
     const result = path.join(run.dir, RESULT_FILE);
     const hasResult = detail && s.end_reason === "done" && fs.existsSync(result);
     const cur = s.steps?.find((x) => !x.done);
+    let ask;
+    if (s.end_reason === "waiting") {
+        try {
+            const r = readAskReply(run.dir);
+            if (r) {
+                const open = r.questions.filter((q) => !q.delivered);
+                ask = { path: askReplyPath(run.dir), total: open.length, unanswered: open.filter((q) => !q.answer?.value.trim()).length };
+            }
+        }
+        catch {
+            ask = { path: askReplyPath(run.dir), total: 0, unanswered: 0 };
+        }
+    }
     return {
         run_id: s.run_id,
         dir: run.dir,
-        state: s.end_reason ? "ended" : live ? "running" : "interrupted",
+        state: s.end_reason === "waiting" ? "waiting" : s.end_reason ? "ended" : live ? "running" : "interrupted",
         live,
         end_reason: s.end_reason,
         outcome: o?.outcome,
@@ -186,6 +203,7 @@ export function buildRunReport(run, project, opts = {}) {
         mail_layout: s.mail_layout,
         workspace_mode: s.workspace_mode,
         last_wake: s.last_wake,
+        ...(ask ? { ask } : {}),
     };
 }
 const projectInfo = (p) => ({ name: p.name, dir: p.dir, lead: p.lead });
@@ -203,6 +221,13 @@ export function buildStatusReport(base, runId) {
     // Mail is per run: count the unread mail of the run being shown.
     const project = run ? bindRunProject(base, run.dir, run.state.mail_layout) : base;
     const report = run ? buildRunReport(run, base) : undefined;
+    let advice = [];
+    try {
+        advice = tidyAdvice(base).map((a) => `${a.agent}: ${a.reason}`);
+    }
+    catch {
+        /* a hint only: never let it break status */
+    }
     return {
         schema_version: 1,
         project: projectInfo(base),
@@ -214,6 +239,7 @@ export function buildStatusReport(base, runId) {
             last_wake: run?.state.last_wake[a.name],
         })),
         run: report,
+        ...(advice.length ? { memory_advice: advice } : {}),
     };
 }
 /** Every run of the project, newest first. */
@@ -274,6 +300,8 @@ function summaryBlock(run, now, c) {
     const lastWake = (s.wakes ?? []).at(-1);
     if (lastWake)
         lines.push(`${L("上一次：")}#${lastWake.round} ${c.cyan(lastWake.agent)} ${okText(c, lastWake.ok)} → ${sentText(lastWake.sent)}`);
+    if (s.ask)
+        lines.push(`${L("等你回答：")}${s.ask.unanswered}/${s.ask.total} 題未答 → ${s.ask.path}`, c.dim(`          填完後執行 agent-lyceum answer ${s.run_id}（或 resume）`));
     lines.push(`${L("流程：")}${flowLine(s, c)}`);
     return lines;
 }
@@ -401,5 +429,7 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     const lines = [`${c.bold("專案：")}${report.project.name}  ${c.dim(`（repo：${report.project.dir}）`)}`, "", ...summaryBlock(run, now, c), "", ...table];
     if (run)
         lines.push("", `輸出 tokens：${tokens(run.output_tokens)}`);
+    if (report.memory_advice?.length)
+        lines.push("", `記憶：${report.memory_advice.join("；")}（建議執行 agent-lyceum memory tidy -p ${report.project.name}；status 只提示，不會自動整理）`);
     return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",
@@ -58,7 +58,7 @@
     "@types/node": "^20.19.43",
     "tsx": "^4.19.0",
     "typescript": "^7.0.2",
-    "vite": "^7.3.7",
+    "vite": "^8.3.3",
     "vitest": "^4.1.11"
   }
 }