agent-lyceum 0.18.0 → 0.20.0

package/dist/run-session.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { realInvoker } from "./adapters/index.js";
+import { agentForCandidate, candidatesFor, Cooldowns, planAttempts, runWithFallback } from "./fallback.js";
 import { briefOf, digestOf, doneContract, mergeSteps, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
 import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, resolveOptionLetters, writeAskReply } from "./ask-reply.js";
@@ -35,6 +36,21 @@ function readIndex(file) {
 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.`;
 }
+/** `runtime/model`, or the runtime alone for its default model. */
+const modelLabel = (c) => (c.model ? `${c.runtime}/${c.model}` : c.runtime);
+/** Each model given up on once, in order, with its last failure (retries on the same model are one entry). */
+function lastPerModel(tried) {
+    const out = [];
+    for (const t of tried) {
+        const last = out.at(-1);
+        const entry = { runtime: t.runtime, ...(t.model ? { model: t.model } : {}), ...(t.kind ? { kind: t.kind } : {}), ...(t.error ? { error: t.error } : {}) };
+        if (last && last.runtime === t.runtime && last.model === t.model)
+            out[out.length - 1] = entry;
+        else
+            out.push(entry);
+    }
+    return out;
+}
 export class RunSession {
     opts;
     resume;
@@ -58,6 +74,8 @@ export class RunSession {
     doneOutcome;
     doneNote;
     failure;
+    /** Models cooling down after a rate limit or quota error; one table for the run, shared by parallel wake-ups. */
+    cooldowns;
     doneVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     openPrRequested = false;
@@ -225,6 +243,7 @@ export class RunSession {
         this.log = log;
         this.guard = guard;
         this.state = state;
+        this.cooldowns = Cooldowns.from(state.cooldowns);
         // Only a segment that starts here has a baseline: a fresh run or a follow-up reopen. A plain resume continues one begun by an earlier process.
         this.sharedAtStart = !resume || opts.followup ? readIndex(sharedIndex(project)) : undefined;
     }
@@ -273,7 +292,7 @@ export class RunSession {
         return pending;
     }
     async wake(agent) {
-        const { invoke, say, cfg, runDir, project, log, state, claims, attempts, noSessionNoted, opts } = this;
+        const { invoke, say, cfg, runDir, project, log, state, claims, attempts, noSessionNoted, opts, cooldowns } = this;
         const queue = listUnread(project, agent.name);
         if (queue.length === 0)
             return { ok: true };
@@ -293,92 +312,153 @@ export class RunSession {
             userPrompt: buildUserPrompt(project, agent, queue, unread.length, (state.reopened?.length ?? 0) > 0),
             timeoutSec: cfg.wake_timeout_sec,
         };
-        let result;
-        for (let attempt = 0; attempt <= cfg.retry; attempt++) {
-            if (state.max_rounds > 0 && state.rounds >= state.max_rounds) {
+        // Without a fallback chain (one candidate) the loop, its output and its records are exactly those of plain retries (spec 20.2 decision 11).
+        const all = candidatesFor(agent);
+        const chain = all.length > 1;
+        const candidates = chain ? planAttempts(agent, cooldowns, Date.now()) : all;
+        // The model a backup's calls stand in for: the one switched away from in this wake, or the cooling-down primary it started past.
+        let replaced = candidates[0]?.primary ? undefined : all[0];
+        let calls = 0;
+        let stoppedByCancel = false;
+        const outcome = await runWithFallback({
+            candidates,
+            legacy: !chain,
+            retry: cfg.retry,
+            cooldowns,
+            cooldownSec: cfg.fallback_cooldown_sec,
+            signal: opts.signal,
+            sleep: opts.sleep,
+            beforeAttempt: (_c, ctx) => {
+                // A cancel that came during the previous call: no new model is tried (without a chain the call still goes ahead, as before).
+                if (chain && ctx.attempt > 0 && opts.signal?.aborted) {
+                    stoppedByCancel = true;
+                    return "stop";
+                }
                 // The round limit (when one is set) ends the run; this message stays unread for the resume.
-                abandonClaim(runDir, claim.id);
-                claims.delete(agent.name);
-                return { ok: false, cancelled: true };
-            }
-            const round = ++state.rounds;
-            const started = Date.now();
-            const att = beginAttempt(runDir, claim.id);
-            say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${agent.runtime})${attempt ? ` — retry ${attempt}` : ""}`);
-            const sessionId = agent.resume ? state.sessions[agent.name] : undefined;
-            const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
-            // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
-            const activeHandling = unread.map((m, i) => ({ ...handling[i], digest: digestOf(m.meta.type, m.body, true) }));
-            state.active[agent.name] = { round, since: new Date(started).toISOString(), handling: activeHandling };
-            this.saveState();
-            result = await invoke({ ...base, signal: opts.signal, logDir: attemptLogDir(runDir, att.id), userPrompt: attempt ? retryPrompt(base.userPrompt, result?.error) : base.userPrompt, sessionId }).catch((e) => ({
-                ok: false,
-                text: "",
-                exitCode: null,
-                timedOut: false,
-                error: e.message,
-            }));
-            if (result.sessionId && agent.resume)
-                state.sessions[agent.name] = result.sessionId;
-            if (result.outputTokens)
-                state.output_tokens += result.outputTokens;
-            delete state.active[agent.name];
-            state.wakes.push({
-                round,
-                agent: agent.name,
-                at: new Date().toISOString(),
-                duration_ms: Date.now() - started,
-                ok: result.ok,
-                output_tokens: result.outputTokens,
-                handling,
-                error: result.error,
-            });
-            state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error };
-            log("wake", {
-                agent: agent.name,
-                runtime: agent.runtime,
-                attempt,
-                ok: result.ok,
-                exit_code: result.exitCode,
-                timed_out: result.timedOut,
-                duration_ms: Date.now() - started,
-                messages: unread.map((m) => m.meta.id),
-                error: result.error,
-            });
-            this.saveState();
-            if (result.ok) {
-                attempts.set(agent.name, finishAttempt(runDir, att.id, "output_ready"));
-                if (agent.resume && !result.sessionId && !state.sessions[agent.name] && !noSessionNoted.has(agent.name)) {
-                    noSessionNoted.add(agent.name);
-                    this.note(`${agent.name} has resume: true but its ${agent.runtime} CLI reported no session id, so every wake-up starts a fresh session.`);
+                return state.max_rounds > 0 && state.rounds >= state.max_rounds ? "stop" : undefined;
+            },
+            onSwitch: (from, to, kind) => {
+                replaced = from;
+                this.syncCooldowns();
+                if (opts.signal?.aborted)
+                    return;
+                say(`  ${agent.name} falling back to ${modelLabel(to)} (${kind ?? "unknown error"})`);
+                this.note(`${agent.name} fell back from ${modelLabel(from)} to ${modelLabel(to)} (${kind ?? "unknown error"}); the backup starts a fresh session and redoes this wake-up. ` +
+                    `Anything the failed attempts already did outside the mailbox (file edits, commands) was not undone: side effects may have happened.`);
+            },
+            invoke: async (c, ctx) => {
+                calls++;
+                this.syncCooldowns();
+                const attempt = ctx.attempt;
+                // A backup runs as the same agent on another runtime/model, in a session of its own.
+                const runAs = agentForCandidate(agent, c);
+                const sessionKey = c.primary ? agent.name : `${agent.name}@${c.key}`;
+                const round = ++state.rounds;
+                const started = Date.now();
+                const att = beginAttempt(runDir, claim.id);
+                const retryN = chain ? ctx.candidateAttempt : attempt;
+                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime})${retryN ? ` — retry ${retryN}` : ""}`);
+                const sessionId = agent.resume ? state.sessions[sessionKey] : undefined;
+                const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
+                // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
+                const activeHandling = unread.map((m, i) => ({ ...handling[i], digest: digestOf(m.meta.type, m.body, true) }));
+                state.active[agent.name] = { round, since: new Date(started).toISOString(), handling: activeHandling };
+                this.saveState();
+                const result = await invoke({
+                    ...base,
+                    agent: runAs,
+                    signal: opts.signal,
+                    logDir: attemptLogDir(runDir, att.id),
+                    userPrompt: attempt ? retryPrompt(base.userPrompt, ctx.previous?.error) : base.userPrompt,
+                    sessionId,
+                }).catch((e) => ({
+                    ok: false,
+                    text: "",
+                    exitCode: null,
+                    timedOut: false,
+                    error: e.message,
+                }));
+                if (result.sessionId && agent.resume)
+                    state.sessions[sessionKey] = result.sessionId;
+                if (result.outputTokens)
+                    state.output_tokens += result.outputTokens;
+                delete state.active[agent.name];
+                // With a chain only: which model ran, what it replaced, why it failed.
+                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || !replaced ? undefined : modelLabel(replaced), kind: result.kind } : {};
+                state.wakes.push({
+                    round,
+                    agent: agent.name,
+                    at: new Date().toISOString(),
+                    duration_ms: Date.now() - started,
+                    ok: result.ok,
+                    output_tokens: result.outputTokens,
+                    handling,
+                    error: result.error,
+                    ...which,
+                });
+                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}) };
+                log("wake", {
+                    agent: agent.name,
+                    runtime: c.runtime,
+                    attempt,
+                    ok: result.ok,
+                    exit_code: result.exitCode,
+                    timed_out: result.timedOut,
+                    duration_ms: Date.now() - started,
+                    messages: unread.map((m) => m.meta.id),
+                    error: result.error,
+                    ...(chain ? { model: c.model, fallback_from: which.fallback_from, kind: result.kind } : {}),
+                });
+                this.saveState();
+                if (result.ok) {
+                    attempts.set(agent.name, finishAttempt(runDir, att.id, "output_ready"));
+                    if (agent.resume && !result.sessionId && !state.sessions[sessionKey] && !noSessionNoted.has(agent.name)) {
+                        noSessionNoted.add(agent.name);
+                        this.note(`${agent.name} has resume: true but its ${c.runtime} CLI reported no session id, so every wake-up starts a fresh session.`);
+                    }
+                    return result;
                 }
-                break;
-            }
-            if (result.cancelled) {
-                // Stopped on purpose: not a failure to report. Its output is set aside and its input stays unread for the resume.
+                if (result.cancelled) {
+                    // Stopped on purpose: not a failure to report. Its output is set aside (its input stays unread for the resume, below).
+                    const parked = parkOutbox(runDir, outboxDir(project, agent.name), att.id);
+                    finishAttempt(runDir, att.id, "failed", { error: "cancelled", parked });
+                    return result;
+                }
+                // A failed attempt's output is never trusted: park it under the attempt, away from the next attempt's result.
                 const parked = parkOutbox(runDir, outboxDir(project, agent.name), att.id);
-                finishAttempt(runDir, att.id, "failed", { error: "cancelled", parked });
-                abandonClaim(runDir, claim.id);
-                claims.delete(agent.name);
-                say(`  ${agent.name} stopped (cancelled)`);
-                return { ok: false, cancelled: true };
-            }
-            // A failed attempt's output is never trusted: park it under the attempt, away from the next attempt's result.
-            const parked = parkOutbox(runDir, outboxDir(project, agent.name), att.id);
-            finishAttempt(runDir, att.id, "failed", { error: result.error, parked });
-            say(`  ${agent.name} failed: ${result.error ?? "unknown error"}`);
-            this.note(`${agent.name} attempt ${att.n} failed (${result.error ?? "unknown error"})${parked.length ? `; ${parked.length} output file(s) set aside in ${path.join("mail", "attempts", att.id, "outbox")}` : ""}. ` +
-                `Anything it already did outside its mailbox (file edits, commands) was not undone: side effects may have happened.`);
-        }
-        if (result?.ok)
+                finishAttempt(runDir, att.id, "failed", { error: result.error, parked });
+                say(`  ${agent.name} failed: ${result.error ?? "unknown error"}`);
+                this.note(`${agent.name} attempt ${att.n} failed (${result.error ?? "unknown error"})${parked.length ? `; ${parked.length} output file(s) set aside in ${path.join("mail", "attempts", att.id, "outbox")}` : ""}. ` +
+                    `Anything it already did outside its mailbox (file edits, commands) was not undone: side effects may have happened.`);
+                return result;
+            },
+        });
+        if (this.syncCooldowns())
+            this.saveState();
+        const { result } = outcome;
+        if (result?.ok) {
             markOutputReady(runDir, claim.id);
-        if (!result?.ok) {
-            // The agent failed every time it was called: the run stops here (see settle) and its message stays unread for the resume.
-            abandonClaim(runDir, claim.id);
-            claims.delete(agent.name);
-            return { ok: false, error: result?.error, attempts: cfg.retry + 1 };
+            return { ok: true };
         }
-        return { ok: true };
+        // The input stays unread for the resume: the round limit, or a cancel (during a call or a backoff).
+        abandonClaim(runDir, claim.id);
+        claims.delete(agent.name);
+        if (outcome.stopped === "beforeAttempt" && !stoppedByCancel)
+            return { ok: false, cancelled: true };
+        if (result?.cancelled || outcome.stopped) {
+            say(`  ${agent.name} stopped (cancelled)`);
+            return { ok: false, cancelled: true };
+        }
+        // The agent failed every time it was called: the run stops here (see settle) and its message stays unread for the resume.
+        return { ok: false, error: result?.error, attempts: calls, ...(chain ? { tried: lastPerModel(outcome.tried) } : {}) };
+    }
+    /** Copy the shared cooldown table into the state (only once something has cooled down); true when it was. */
+    syncCooldowns() {
+        const table = this.cooldowns.toJSON();
+        if (!Object.keys(table).length)
+            return false;
+        this.state.cooldowns = table;
+        return true;
     }
     /**
      * A finished member's files go from its worktree into the repo before anyone reads its mail, so the lead
@@ -543,7 +623,8 @@ export class RunSession {
         const failedIdx = results.findIndex((r) => !r.ok && !r.cancelled);
         if (failedIdx >= 0) {
             const failed = must(batch[failedIdx], "failed agent");
-            this.failure = { agent: failed.name, error: results[failedIdx]?.error, attempts: results[failedIdx]?.attempts ?? this.cfg.retry + 1 };
+            const r = results[failedIdx];
+            this.failure = { agent: failed.name, error: r?.error, attempts: r?.attempts ?? this.cfg.retry + 1, ...(r?.tried ? { tried: r.tried } : {}) };
             state.failure = this.failure;
             this.endReason = failed.name === project.lead ? "lead_failed" : "agent_failed";
             return;

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"];