agent-lyceum 0.18.0 → 0.19.0

package/dist/run-store.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedProject } from "./config.js";
 import type { DigestSection, Step } from "./format.js";
-import type { RunOutcome } from "./schema.js";
+import { type ErrorKind, type Runtime, type RunOutcome } from "./schema.js";
 import type { ResultBranch } from "./worktree.js";
 export declare const STATE_FILE = "state.json";
 export declare const STATE_SCHEMA_VERSION = 2;
@@ -36,6 +36,27 @@ export interface WakeRecord {
     /** Mail this wake handed to others; `to` is "(done)" for the lead's final message. */
     sent?: SentTopic[];
     error?: string;
+    /** With a fallback chain only: the runtime and model this call ran on. */
+    runtime?: Runtime;
+    model?: string;
+    /** With a fallback chain only: the `runtime/model` this call replaced (set on a backup's calls). */
+    fallback_from?: string;
+    /** With a fallback chain only: why the call failed. */
+    kind?: ErrorKind;
+}
+/** A model given up on during a wake with a fallback chain, for `failure.tried`. */
+export interface TriedModel {
+    runtime: Runtime;
+    model?: string;
+    kind?: ErrorKind;
+    error?: string;
+}
+/** The run stopped because an agent kept failing: who, the last error, how many times it was called; `tried` only with a fallback chain. */
+export interface RunFailure {
+    agent: string;
+    error?: string;
+    attempts: number;
+    tried?: TriedModel[];
 }
 export interface RunState {
     /** 1 for runs written before versioning; 2 for runs with their own mailboxes. */
@@ -84,10 +105,13 @@ export interface RunState {
     pr_url?: string;
     sessions: Record<string, string>;
     output_tokens: number;
+    /** `runtime`/`model` only for agents with a fallback chain. */
     last_wake: Record<string, {
         at: string;
         ok: boolean;
         error?: string;
+        runtime?: Runtime;
+        model?: string;
     }>;
     /** Process running this dispatcher, so a monitor can tell "running" from "interrupted". */
     pid: number;
@@ -98,11 +122,12 @@ export interface RunState {
     /** Finished wakes, oldest first. */
     wakes: WakeRecord[];
     /** Set when the run stopped because an agent kept failing: who, the last error, how many times it was called. */
-    failure?: {
-        agent: string;
-        error?: string;
-        attempts: number;
-    };
+    failure?: RunFailure;
+    /** Models cooling down after `rate_limit`/`quota` (`<runtime>/<model>` → until when); absent until one is. */
+    cooldowns?: Record<string, {
+        until: string;
+        kind: ErrorKind;
+    }>;
     /** Checklist progress: seeded from the task, then replaced by the lead's latest `## Steps` (after a reopen, added to `step_base`). */
     steps?: Step[];
     /** The checklist as it stood at the last reopen: the follow-up's steps are shown after it, and its open steps do not hold up the follow-up's done. */

package/dist/run-store.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { atomicWrite } from "./fs-util.js";
+import { ERROR_KINDS, RUNTIMES } from "./schema.js";
 export const STATE_FILE = "state.json";
 export const STATE_SCHEMA_VERSION = 2;
 /** `20261006T010203456Z-<128 random bits>`: sorts by start time and cannot collide, even for two starts in one millisecond. */
@@ -11,6 +12,19 @@ export function newRunId(d = new Date()) {
     return `${t}-${crypto.randomBytes(16).toString("hex")}`;
 }
 const nonNeg = z.number().finite();
+const CooldownEntry = z.object({ until: z.string(), kind: z.enum(ERROR_KINDS) });
+/** `state.cooldowns` is advisory: keep the entries that parse and drop the rest, so one bad entry never makes the run unreadable. */
+function lenientCooldowns(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        const e = CooldownEntry.safeParse(v);
+        if (e.success)
+            out[k] = e.data;
+    }
+    return out;
+}
 const WireState = z
     .object({
     schema_version: z.number().int().optional(),
@@ -39,7 +53,15 @@ const WireState = z
     wakes: z.array(z.any()).optional(),
     solo_agent: z.string().optional(),
     steps: z.array(z.object({ text: z.string(), done: z.boolean() })).optional(),
-    failure: z.object({ agent: z.string(), error: z.string().optional(), attempts: z.number() }).optional(),
+    failure: z
+        .object({
+        agent: z.string(),
+        error: z.string().optional(),
+        attempts: z.number(),
+        tried: z.array(z.object({ runtime: z.enum(RUNTIMES), model: z.string().optional(), kind: z.enum(ERROR_KINDS).optional(), error: z.string().optional() })).optional(),
+    })
+        .optional(),
+    cooldowns: z.unknown().transform(lenientCooldowns).optional(),
     step_base: z.array(z.object({ text: z.string(), done: z.boolean() })).optional(),
     name: z.string().optional(),
     reopened: z.array(z.object({ at: z.string() })).optional(),

package/dist/schema.d.ts

@@ -11,6 +11,32 @@ export declare function inferRuntime(model: string | undefined): Runtime | undef
 /** How much of the web an agent may use: nothing, search only, or search plus fetching pages. Unset leaves each runtime's own default alone. */
 export declare const WEB_LEVELS: readonly ["none", "search", "fetch"];
 export type WebLevel = (typeof WEB_LEVELS)[number];
+/** Why a wake failed, as far as the CLI's output reveals; decides whether to retry, fall back, or stop. */
+export declare const ERROR_KINDS: readonly ["rate_limit", "quota", "timeout", "network", "crash", "auth", "unknown"];
+export type ErrorKind = (typeof ERROR_KINDS)[number];
+/** One link of a fallback chain after resolution: runtime and model are filled in (model "" = the runtime's own default). */
+export interface FallbackEntry {
+    runtime: Runtime;
+    model: string;
+    effort?: Effort;
+}
+/** A fallback entry as written in a file: `runtime` may be omitted (inferred from `model`, else the agent's). */
+export declare const FallbackEntryPartial: z.ZodObject<{
+    runtime: z.ZodOptional<z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        minimal: "minimal";
+        xhigh: "xhigh";
+    }>>;
+}, z.core.$strict>;
+export type FallbackEntryPartialT = z.infer<typeof FallbackEntryPartial>;
 export declare const AgentPartial: z.ZodObject<{
     runtime: z.ZodOptional<z.ZodEnum<{
         "claude-code": "claude-code";
@@ -39,6 +65,21 @@ export declare const AgentPartial: z.ZodObject<{
         none: "none";
         search: "search";
     }>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            xhigh: "xhigh";
+        }>>;
+    }, z.core.$strict>>>;
     owns: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strict>;
 export type AgentPartialT = z.infer<typeof AgentPartial>;
@@ -51,6 +92,22 @@ export declare const DispatcherPartial: z.ZodObject<{
     strict: z.ZodOptional<z.ZodBoolean>;
     workspace_mode: z.ZodOptional<z.ZodUnknown>;
     log_max_bytes: z.ZodOptional<z.ZodNumber>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            xhigh: "xhigh";
+        }>>;
+    }, z.core.$strict>>>;
+    fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */
 export declare const REMOVED_DISPATCHER_KEYS: readonly ["max_parallel", "max_concurrent_runs", "workspace_mode"];
@@ -84,6 +141,21 @@ export declare const GlobalConfig: z.ZodObject<{
             none: "none";
             search: "search";
         }>>;
+        fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            runtime: z.ZodOptional<z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                max: "max";
+                medium: "medium";
+                minimal: "minimal";
+                xhigh: "xhigh";
+            }>>;
+        }, z.core.$strict>>>;
         owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
@@ -101,6 +173,22 @@ export declare const ProjectConfig: z.ZodObject<{
         strict: z.ZodOptional<z.ZodBoolean>;
         workspace_mode: z.ZodOptional<z.ZodUnknown>;
         log_max_bytes: z.ZodOptional<z.ZodNumber>;
+        fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            runtime: z.ZodOptional<z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                max: "max";
+                medium: "medium";
+                minimal: "minimal";
+                xhigh: "xhigh";
+            }>>;
+        }, z.core.$strict>>>;
+        fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         runtime: z.ZodOptional<z.ZodEnum<{
@@ -130,6 +218,21 @@ export declare const ProjectConfig: z.ZodObject<{
             none: "none";
             search: "search";
         }>>;
+        fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            runtime: z.ZodOptional<z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                max: "max";
+                medium: "medium";
+                minimal: "minimal";
+                xhigh: "xhigh";
+            }>>;
+        }, z.core.$strict>>>;
         owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
@@ -140,6 +243,8 @@ export interface DispatcherSettings {
     strict: boolean;
     /** log.jsonl is rotated to log.1.jsonl past this size; 0 = never. */
     log_max_bytes: number;
+    /** How long a primary that hit rate_limit/quota is skipped within a run, unless the CLI says when to come back. */
+    fallback_cooldown_sec: number;
 }
 export declare const DISPATCHER_DEFAULTS: DispatcherSettings;
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */

package/dist/schema.js

@@ -20,12 +20,22 @@ export function inferRuntime(model) {
 }
 /** How much of the web an agent may use: nothing, search only, or search plus fetching pages. Unset leaves each runtime's own default alone. */
 export const WEB_LEVELS = ["none", "search", "fetch"];
+/** Why a wake failed, as far as the CLI's output reveals; decides whether to retry, fall back, or stop. */
+export const ERROR_KINDS = ["rate_limit", "quota", "timeout", "network", "crash", "auth", "unknown"];
 const Memory = z
     .object({
     global: z.string().optional(),
     project: z.string().optional(),
 })
     .strict();
+/** A fallback entry as written in a file: `runtime` may be omitted (inferred from `model`, else the agent's). */
+export const FallbackEntryPartial = z
+    .object({
+    runtime: z.enum(RUNTIMES).optional(),
+    model: z.string().optional(),
+    effort: z.enum(EFFORTS).optional(),
+})
+    .strict();
 export const AgentPartial = z
     .object({
     runtime: z.enum(RUNTIMES).optional(),
@@ -38,6 +48,7 @@ export const AgentPartial = z
     can_edit_agent_md: z.boolean().optional(),
     can_ask_user: z.boolean().optional(),
     allow_web: z.enum(WEB_LEVELS).optional(),
+    fallback: z.array(FallbackEntryPartial).optional(),
     /** Removed setting: still accepted (any value) so old files load; ignored, with a warning from `validate`. */
     owns: z.unknown().optional(),
 })
@@ -52,6 +63,8 @@ export const DispatcherPartial = z
     strict: z.boolean().optional(),
     workspace_mode: z.unknown().optional(),
     log_max_bytes: z.number().int().min(0).optional(),
+    fallback: z.array(FallbackEntryPartial).optional(),
+    fallback_cooldown_sec: z.number().int().min(0).optional(),
 })
     .strict();
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */
@@ -76,6 +89,7 @@ export const DISPATCHER_DEFAULTS = {
     retry: 2,
     strict: false,
     log_max_bytes: 8 * 1024 * 1024,
+    fallback_cooldown_sec: 300,
 };
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */
 export const RUN_OUTCOMES = ["completed", "partial", "blocked", "failed", "waiting", "cancelled"];

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.19.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",