agent-lyceum 0.18.0 → 0.20.0

package/dist/status.d.ts

@@ -1,4 +1,4 @@
-import { type ActiveWake, type EndReason, type RunState, type WakeRecord } from "./run-store.js";
+import { type ActiveWake, type EndReason, type RunFailure, type RunState, type WakeRecord } from "./run-store.js";
 import type { RunOutcome } from "./schema.js";
 import type { ResolvedProject } from "./config.js";
 import { type DigestSection, type Step } from "./format.js";
@@ -72,11 +72,7 @@ export interface RunReport {
     /** 0 = no limit. */
     max_rounds: number;
     /** Set when an agent kept failing and the run stopped: `resume` after fixing the cause. */
-    failure?: {
-        agent: string;
-        error?: string;
-        attempts: number;
-    };
+    failure?: RunFailure;
     output_tokens: number;
     task_source: "text" | "file";
     task_path?: string;
@@ -123,6 +119,19 @@ export interface AgentReport {
         ok: boolean;
         error?: string;
     };
+    /** Only for an agent with a fallback chain: the model it last ran on (or its own, before any wake). */
+    model?: string;
+    /** Only when the agent's latest wake ran on a backup: what it replaced and why. */
+    fallback?: {
+        from: string;
+        kind: string;
+    };
+    /** Only for an agent with a fallback chain: its models that are cooling down now (`model` is `<runtime>/<model>`). */
+    cooldowns?: {
+        model: string;
+        kind: string;
+        remaining_sec: number;
+    }[];
 }
 export interface StatusReport {
     schema_version: 1;
@@ -153,7 +162,7 @@ export declare function buildRunReport(run: {
     detail?: boolean;
 }): RunReport;
 /** The status of a project: its agents and one run (the newest running one, else the newest, or the one named by `runId`). */
-export declare function buildStatusReport(base: ResolvedProject, runId?: string): StatusReport;
+export declare function buildStatusReport(base: ResolvedProject, runId?: string, now?: number): StatusReport;
 /** Every run of the project, newest first. */
 export declare function buildTaskListReport(project: ResolvedProject): TaskListReport;
 /** Live view: summary and agent table, plus the latest run and any run still going, wake by wake. */

package/dist/status.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { askReplyPath, readAskReply } from "./ask-reply.js";
 import { RESULT_FILE } from "./dispatcher.js";
 import { bindRunProject, loadRunState, outcomeOf, roundsLabel, runLabel } from "./run-store.js";
+import { candidatesFor } from "./fallback.js";
 import { briefOf, digestOf } from "./format.js";
 import { listUnread } from "./mailbox.js";
 import { tidyAdvice } from "./memory-tidy.js";
@@ -226,8 +227,37 @@ export function buildRunReport(run, project, opts = {}) {
     };
 }
 const projectInfo = (p) => ({ name: p.name, dir: p.dir, lead: p.lead });
+/** The fallback part of an agent's report: nothing at all for an agent without a chain. */
+function fallbackView(a, state, now) {
+    if (!a.fallback.length || !a.runtime)
+        return {};
+    const lw = state?.last_wake[a.name];
+    const ran = lw?.runtime ? lw : undefined;
+    const model = ran ? ran.model : a.model;
+    const mine = (state?.wakes ?? []).filter((w) => w.agent === a.name);
+    const last = mine.at(-1);
+    let fallback;
+    if (last?.fallback_from) {
+        // The reason is on the failed wake just before: the nearest earlier wake of this agent that has a kind.
+        let kind = "unknown";
+        for (let i = mine.length - 2; i >= 0; i--) {
+            const k = mine[i].kind;
+            if (k) {
+                kind = k;
+                break;
+            }
+        }
+        fallback = { from: last.fallback_from, kind };
+    }
+    const keys = new Set(candidatesFor(a).map((c) => c.key));
+    const cooldowns = Object.entries(state?.cooldowns ?? {})
+        .filter(([k]) => keys.has(k))
+        .map(([k, v]) => ({ model: k, kind: v.kind, remaining_sec: Math.ceil((Date.parse(v.until) - now) / 1000) }))
+        .filter((c) => Number.isFinite(c.remaining_sec) && c.remaining_sec > 0);
+    return { runtime: ran?.runtime ?? a.runtime, ...(model ? { model } : {}), ...(fallback ? { fallback } : {}), ...(cooldowns.length ? { cooldowns } : {}) };
+}
 /** The status of a project: its agents and one run (the newest running one, else the newest, or the one named by `runId`). */
-export function buildStatusReport(base, runId) {
+export function buildStatusReport(base, runId, now = Date.now()) {
     let run;
     if (runId) {
         const dir = path.join(base.paths.runs, runId);
@@ -257,6 +287,7 @@ export function buildStatusReport(base, runId) {
             unread: listUnread(project, a.name).length,
             can_message: (a.canMessage === "all" ? Object.keys(project.agents) : a.canMessage).filter((n) => n !== a.name),
             last_wake: run?.state.last_wake[a.name],
+            ...fallbackView(a, run?.state, now),
         })),
         run: report,
         ...(advice.length ? { memory_advice: advice } : {}),
@@ -425,6 +456,20 @@ export function formatTaskListReport(report, color = false) {
 export function formatStatus(base, now = Date.now(), color = false) {
     return formatStatusReport(buildStatusReport(base), now, color);
 }
+const shortSec = (sec) => (sec < 60 ? `${sec}s` : `${Math.floor(sec / 60)}m${String(sec % 60).padStart(2, "0")}s`);
+/** `runtime/model`, or the runtime alone for its default model (cooldown keys end in `/` then). */
+const modelName = (key) => key.replace(/\/$/, "");
+/** Agents running on a backup and models cooling down; empty for a run without fallback. */
+function fallbackLines(agents, c) {
+    const out = [];
+    for (const a of agents) {
+        if (a.fallback)
+            out.push(`  ${c.cyan(a.name)} ${c.yellow(`備援中 fallback: ${a.fallback.kind}`)} (${modelName(`${a.runtime ?? "?"}/${a.model ?? ""}`)})`);
+        for (const k of a.cooldowns ?? [])
+            out.push(`  ${c.cyan(a.name)} ${c.yellow(`冷卻中：${modelName(k.model)} 剩 ${shortSec(k.remaining_sec)}`)}（${k.kind}）`);
+    }
+    return out;
+}
 export function formatStatusReport(report, now = Date.now(), color = false) {
     const c = paint(color);
     const run = report.run;
@@ -452,6 +497,9 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     const table = rows.map((r, ri) => r.map((_, i) => cell(r, ri, i)).join("  ").trimEnd());
     table.splice(1, 0, c.dim(w.map((n) => "-".repeat(n)).join("  ")));
     const lines = [`${c.bold("專案：")}${report.project.name}  ${c.dim(`（repo：${report.project.dir}）`)}`, "", ...summaryBlock(run, now, c), "", ...table];
+    const fb = fallbackLines(report.agents, c);
+    if (fb.length)
+        lines.push("", ...fb);
     if (run)
         lines.push("", `輸出 tokens：${tokens(run.output_tokens)}`);
     if (report.memory_advice?.length)

package/dist/validate.js

@@ -25,6 +25,7 @@ export function validateProject(project) {
         if (a.effort && a.runtime && !RUNTIME_EFFORTS[a.runtime].includes(a.effort)) {
             err(`Agent "${a.name}": effort "${a.effort}" is not supported by ${a.runtime} (use ${RUNTIME_EFFORTS[a.runtime].join(", ")}).`);
         }
+        validateFallback(project, a, err);
         if (!fs.existsSync(a.agentMd))
             err(`Agent "${a.name}": AGENT.md not found at ${a.agentMd}`);
         if (!a.memory.global && !a.memory.project)
@@ -75,6 +76,41 @@ export function validateProject(project) {
     }
     return { issues, enforcement, ok: !issues.some((i) => i.level === "error") };
 }
+const PARITY_FIELDS = ["memory", "agentMd", "otherContext", "shared", "repoInstructions"];
+const norm = (m) => (m ?? "").trim().toLowerCase();
+/** Load-time (fail closed) checks of one agent's fallback chain: well-formed, not a no-op, and no weaker at write-scope than the primary. */
+function validateFallback(project, a, err) {
+    for (const bad of a.fallbackInvalid) {
+        err(bad.reason === "empty"
+            ? `agent ${a.name}: fallback #${bad.index + 1} needs a model or a runtime.`
+            : `agent ${a.name}: fallback #${bad.index + 1} has no recognizable runtime (set runtime, or use a recognizable model).`);
+    }
+    const primary = a.runtime ? enforcementFor(project, a) : undefined;
+    for (const f of a.fallback) {
+        const label = `${f.runtime}/${f.model || "(default model)"}`;
+        if (f.runtime === a.runtime && norm(f.model) === norm(a.model)) {
+            // A chain shared through dispatcher.fallback may already contain this agent's primary: just skip it then.
+            if (!a.fallbackShared)
+                err(`agent ${a.name}: fallback ${label} is the same as the primary runtime and model.`);
+            continue;
+        }
+        if (f.effort && !RUNTIME_EFFORTS[f.runtime].includes(f.effort)) {
+            err(`agent ${a.name}: fallback ${label}: effort "${f.effort}" is not supported by ${f.runtime} (use ${RUNTIME_EFFORTS[f.runtime].join(", ")}).`);
+        }
+        if (!primary)
+            continue;
+        // `prompt-only` is the one level that is no enforcement at all; everything else (os, tool-rules, post-hoc) still holds the line.
+        const swapped = enforcementFor(project, { ...a, runtime: f.runtime, model: f.model || undefined, effort: f.effort });
+        for (const k of PARITY_FIELDS) {
+            const from = primary[k];
+            const to = swapped[k];
+            if (from === "n/a" || to === "n/a")
+                continue;
+            if (to === "prompt-only" && from !== "prompt-only")
+                err(`agent ${a.name}: fallback ${label} cannot enforce ${k} (${from} -> ${to})`);
+        }
+    }
+}
 export function formatEnforcement(list) {
     const header = ["agent", "runtime", "memory", "AGENT.md", "others' ctx", "handoff", "repo CLAUDE/AGENTS"];
     const rows = [header];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",