@a-t-h-i/bot-lobby 0.6.6 → 0.6.8

package/src/ask/tool.ts

@@ -65,23 +65,30 @@ export function invalidQuestions(questions: readonly AskQuestion[]): string | un
   return undefined;
 }
 
+/** What the model does with questions the user left unanswered: wait, never fill them in. */
+const STILL_OPEN = "Do not assume answers, do not pick the recommended options, and do not go on with work that depends on them. Say in one short line that the questions are waiting, end your turn, and put them to the user again when they next write.";
+const NOT_ANSWERED = `The user left the questions without answering. ${STILL_OPEN}`;
+
 /** What the model reads back: each question with its answer, or that it was skipped. */
 export function answerSummary(questions: readonly AskQuestion[], result: AskResult): string {
   if (result.cancelled && result.answers.length === 0) {
     // A relay that could not ask anyone (auto mode) says why.
     if (result.globalNote) return result.globalNote;
-    return "The user put the questions away without answering. Do not ask the same again right away: go on with your best judgement and say what you assumed, or ask something narrower.";
+    return NOT_ANSWERED;
   }
   const lines = questions.map((question, index) => {
     const answer = result.answers.find((entry) => entry.questionIndex === index);
     const head = `${index + 1}. [${question.header}] ${question.question.replace(/\s+/g, " ").trim()}`;
     if (!answer) return `${head}\n   → (not answered)`;
     const text = answer.kind === "multi" ? (answer.selected ?? []).join(", ") : answer.answer ?? "";
-    return `${head}\n   → ${text}${answer.kind === "custom" ? " (in the user's own words)" : ""}${answer.notes ? `\n   note: ${answer.notes}` : ""}`;
+    // A several-line answer keeps its lines under the arrow.
+    const lines = (value: string) => value.replace(/\n/g, "\n     ");
+    return `${head}\n   → ${lines(text)}${answer.kind === "custom" ? " (in the user's own words)" : ""}${answer.notes ? `\n   note: ${lines(answer.notes)}` : ""}`;
   });
   return [
     result.cancelled ? "The user answered some questions, then put the rest away:" : "The user answered:",
     ...lines,
+    ...(result.cancelled ? ["", `The questions marked "(not answered)" are still open. ${STILL_OPEN}`] : []),
     ...(result.globalNote ? ["", `Note: ${result.globalNote}`] : []),
   ].join("\n");
 }

package/src/ask/view.ts

@@ -65,10 +65,13 @@ function optionLines(state: AskState, question: AskQuestion, width: number, them
   const lead = `${pointer} ${paint(theme, own ? "accent" : "dim", "✎")}    `;
   const room = Math.max(1, width - textWidth(lead));
   if (state.editing) {
-    const draft = wrap(`${state.draft}▏`, room);
+    // Each line of the answer wraps on its own, so Shift+Enter shows as a new row.
+    const draft = `${state.draft}▏`.split("\n").flatMap((line) => (line ? wrap(line, room) : [""]));
     lines.push(`${lead}${paint(theme, "accent", draft[0] ?? "")}`, ...draft.slice(1).map((line) => `${" ".repeat(textWidth(lead))}${paint(theme, "accent", line)}`));
   } else {
-    lines.push(`${lead}${own ? paint(theme, "accent", `“${own}”`) : paint(theme, ownFocused ? "text" : "dim", OWN_ANSWER)}`);
+    // A several-line answer shows on one row, its line breaks marked.
+    const shown = own?.replace(/\s*\n\s*/g, " ⏎ ");
+    lines.push(`${lead}${shown ? paint(theme, "accent", `“${shown}”`) : paint(theme, ownFocused ? "text" : "dim", OWN_ANSWER)}`);
   }
   return lines;
 }
@@ -112,14 +115,15 @@ function previewBox(preview: Preview, width: number, rows: number, theme: LobbyT
 }
 
 function hints(state: AskState, question: AskQuestion, width: number, theme?: LobbyTheme): string[] {
+  if (state.leaving) return wrap(paint(theme, "warning", "Leave without answering? The oracle will not guess for you. enter leaves · any other key keeps answering"), width);
   const parts = state.editing
-    ? ["enter keep it", "esc back to the options"]
+    ? ["enter keep it", "shift+enter new line", "esc back to the options"]
     : [
         "↑↓ move",
         question.multiSelect ? "space pick · enter next" : "enter choose",
         `1-${question.options.length} pick`,
         ...(state.questions.length > 1 ? ["←→ questions"] : []),
-        "esc put away",
+        "esc leave",
       ];
   return wrap(paint(theme, "dim", parts.join(" · ")), width);
 }

package/src/classifier/instance.ts

@@ -11,6 +11,7 @@ import { isSubagentProcess } from "../pi/quiet.ts";
 import { Classifier } from "./classifier.ts";
 import { registerJevProvider, type KeySource, type KeyStatus } from "./hosts.ts";
 import { fileHinter, type FileHinter, type FileScope } from "./files.ts";
+import { knowledgePicker, type KnowledgePicker } from "./knowledge.ts";
 import { lobbyFeed } from "../lobby/feed.ts";
 import { triageLine, triageWithContext } from "./triage.ts";
 import type { TaskTriage } from "../schemas/task.ts";
@@ -45,6 +46,11 @@ export function hintsFor(scope: FileScope): FileHinter {
   return fileHinter(classifier(), scope, (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
 }
 
+/** Relevant knowledge for agents, with what Jev kept of each long file logged to the lobby's activity feed. */
+export function knowledgeFor(): KnowledgePicker {
+  return knowledgePicker(classifier(), (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
+}
+
 /** Triage a request for a task in a tree, logged to the lobby's activity feed; undefined when triage is off or fails. */
 export async function triageFor(scope: FileScope, request: string, signal?: AbortSignal): Promise<TaskTriage | undefined> {
   const triage = await triageWithContext(classifier(), scope, request, signal);

package/src/classifier/knowledge.ts

@@ -0,0 +1,158 @@
+/**
+ * Relevant knowledge. An agent's knowledge, standards and decisions are put in
+ * its prompt, not looked up, so a gate ("does this step need the knowledge
+ * base?") would have to guess before the agent knows what it needs, and a wrong
+ * "no" is silent. What Jev does safely instead is the ranking the keyword
+ * selector does badly: when a file is longer than the prompt has room for, Jev
+ * judges each of its sections against the step (one yes/no per section) and the
+ * ones that bear on it stay. A file that fits goes in whole and costs nothing.
+ *
+ * Whatever is left out is said so, with the file's path, so an agent that does
+ * need it reads the rest itself. Any failure, timeout or switch-off keeps the
+ * keyword selection, which is what agents got before.
+ */
+import { basename } from "node:path";
+import { score, selectRelevant, splitSections, tokenize, type KnowledgeInput, type KnowledgeSelection } from "../knowledge/selector.ts";
+import type { Classifier } from "./classifier.ts";
+import { noul, yesOf, type SystemOneRequest } from "./client.ts";
+import { clip } from "./limits.ts";
+
+/** How many characters of each knowledge file a prompt has room for. */
+export const KNOWLEDGE_BUDGET_CHARS = 4000;
+/** A section is judged on its first characters; the whole section is kept when it stays. */
+export const SECTION_EXCERPT_CHARS = 700;
+/** Sections judged per file; a longer file is narrowed by keywords first. */
+export const MAX_SECTIONS = 60;
+/** The step waits this long for Jev, then goes with keywords. */
+export const KNOWLEDGE_BUDGET_MS = 1500;
+
+/** The three files a prompt carries: `knowledge`, `standards` and `decisions`. */
+export type KnowledgeSlice = keyof KnowledgeSelection;
+export type KnowledgePaths = Partial<Record<KnowledgeSlice, string>>;
+
+export interface SectionCall {
+  request: SystemOneRequest;
+  /** The section each question key stands for, by index into the file's sections. */
+  keys: Map<string, number>;
+}
+
+/** One request that asks about each candidate section of a file. */
+export function sectionRequest(task: string, sections: readonly string[], candidates: readonly number[]): SectionCall {
+  const entries: Record<string, string> = {};
+  const questions: SystemOneRequest["questions"] = {};
+  const keys = new Map<string, number>();
+  candidates.forEach((index, position) => {
+    const key = `s${position + 1}`;
+    entries[key] = clip(sections[index]!, SECTION_EXCERPT_CHARS);
+    questions[key] = noul(`Does \`sections.${key}\` hold a fact, rule or decision that an agent doing \`task\` should have in front of it? Yes when it bears on the code, files, conventions or choices the task touches; no when it is about something else or only shares words with it.`);
+    keys.set(key, index);
+  });
+  return { request: { state: { task: clip(task, 3000), sections: entries }, questions }, keys };
+}
+
+/** The sections to judge: all of them, or the `MAX_SECTIONS` that share the most words with the task. */
+export function candidateSections(task: string, sections: readonly string[]): number[] {
+  const all = sections.map((_, index) => index);
+  if (sections.length <= MAX_SECTIONS) return all;
+  const tokens = tokenize(task);
+  const scored = all.map((index) => ({ index, hits: score(sections[index]!, tokens) }));
+  scored.sort((a, b) => b.hits - a.hits || b.index - a.index);
+  return scored.slice(0, MAX_SECTIONS).map((entry) => entry.index).sort((a, b) => a - b);
+}
+
+/** What was kept of a file: its text and how many of its sections that was. */
+export interface Kept {
+  text: string;
+  kept: number;
+  total: number;
+}
+
+/**
+ * The most relevant sections that fit `budget`, in the order of the file. A
+ * section too long to fit on its own is cut to fit when nothing else is kept.
+ */
+export function keepSections(sections: readonly string[], relevance: ReadonlyMap<number, number>, floor: number, budget: number): Kept {
+  const wanted = [...relevance].filter(([, value]) => value >= floor).sort((a, b) => b[1] - a[1] || a[0] - b[0]);
+  const chosen: number[] = [];
+  const texts = new Map<number, string>();
+  let used = 0;
+  for (const [index] of wanted) {
+    const text = sections[index]!;
+    if (used + text.length <= budget) {
+      chosen.push(index);
+      texts.set(index, text);
+      used += text.length + 2;
+    } else if (chosen.length === 0) {
+      chosen.push(index);
+      texts.set(index, clip(text, budget));
+      used = budget;
+    }
+  }
+  chosen.sort((a, b) => a - b);
+  return { text: chosen.map((index) => texts.get(index)!).join("\n\n").trim(), kept: chosen.length, total: sections.length };
+}
+
+/** The line that tells an agent what it was not given, and where all of it is. */
+export function leftOutNote(kept: Kept, name: string, path?: string): string {
+  const where = path ? ` The whole file is ${path}.` : "";
+  return kept.kept === 0
+    ? `_No section of ${name} bears on this step (${kept.total} sections).${where}_`
+    : `_Kept ${kept.kept} of ${kept.total} sections of ${name} for this step.${where}_`;
+}
+
+/** Picks what an agent's prompt carries of its knowledge files. */
+export interface KnowledgePicker {
+  select(task: string, files: KnowledgeInput, options?: { signal?: AbortSignal; paths?: KnowledgePaths }): Promise<KnowledgeSelection>;
+}
+
+const SLICES: readonly KnowledgeSlice[] = ["knowledge", "standards", "decisions"];
+
+/**
+ * Jev's picks for one file over the budget, or undefined when it cannot judge
+ * (off, failed, out of time, no key): the caller then uses keywords.
+ */
+async function rank(classifier: Classifier, task: string, content: string, budget: number, options: { signal?: AbortSignal }): Promise<{ kept: Kept; sections: string[]; ms: number } | undefined> {
+  const sections = splitSections(content.trim());
+  if (sections.length < 2) return undefined;
+  const call = sectionRequest(task, sections, candidateSections(task, sections));
+  const result = await classifier.ask("knowledge", call.request, { ...(options.signal ? { signal: options.signal } : {}), timeoutMs: Math.min(classifier.config.timeoutMs, KNOWLEDGE_BUDGET_MS) });
+  if (!result) return undefined;
+  const relevance = new Map<number, number>();
+  for (const [key, index] of call.keys) {
+    const value = yesOf(result.answers, key);
+    if (value !== undefined) relevance.set(index, value);
+  }
+  // An answer to none of the questions says nothing: keywords decide.
+  if (relevance.size === 0) return undefined;
+  return { kept: keepSections(sections, relevance, classifier.config.thresholds.knowledgeRelevantAt, budget), sections, ms: result.ms };
+}
+
+/**
+ * A picker on Jev. Files that fit the prompt are untouched; a longer one keeps
+ * the sections Jev judges to bear on the step, with a note of what was left
+ * out. Standards are the exception to an empty result: they are rules for all
+ * work, so when Jev sees none that applies the keyword selection stands.
+ */
+export function knowledgePicker(classifier: Classifier, log?: (text: string) => void, budget = KNOWLEDGE_BUDGET_CHARS): KnowledgePicker {
+  return {
+    async select(task, files, options = {}) {
+      const plain = (kind: KnowledgeSlice) => selectRelevant(task, files[kind] ?? "", budget);
+      const picked = await Promise.all(SLICES.map(async (kind): Promise<string> => {
+        const content = files[kind] ?? "";
+        if (content.trim().length <= budget || !task.trim() || !classifier.enabled("knowledge")) return plain(kind);
+        try {
+          const ranked = await rank(classifier, task, content, budget, options.signal ? { signal: options.signal } : {});
+          if (!ranked) return plain(kind);
+          const path = options.paths?.[kind];
+          const name = path ? basename(path) : kind;
+          if (ranked.kept.kept === 0 && kind === "standards") return plain(kind);
+          log?.(`knowledge: kept ${ranked.kept.kept} of ${ranked.kept.total} sections of ${name} · ${ranked.ms} ms`);
+          return [ranked.kept.text, leftOutNote(ranked.kept, name, path)].filter(Boolean).join("\n\n");
+        } catch {
+          return plain(kind);
+        }
+      }));
+      return { knowledge: picked[0]!, standards: picked[1]!, decisions: picked[2]! };
+    },
+  };
+}

package/src/classifier/review.ts

@@ -0,0 +1,146 @@
+/**
+ * Jev's quick read of a pull request, for the Git tab: how big the change is,
+ * how likely it is risky, to break callers, to touch security-sensitive code
+ * or to change behaviour without tests, and what kind of change it is — in
+ * one call, in a moment, without writing a word. It is a triage, not a review:
+ * it says whether a full review by an agent is worth its tokens.
+ */
+import type { Classifier } from "./classifier.ts";
+import { choice, choiceOf, noul, score, scoreOf, yesOf, type SystemOneRequest } from "./client.ts";
+import { clip } from "./limits.ts";
+import { TRIAGE_SIZES } from "./triage.ts";
+import type { TriageSize } from "../schemas/task.ts";
+
+const SIZE_LEVELS = [
+  "trivial: a one-line or mechanical change (a rename, a typo, a version bump)",
+  "small: a few files in one area, following an existing pattern",
+  "medium: several files or two areas, with some design decisions",
+  "large: a cross-cutting change, a new subsystem, a migration or an architecture change",
+];
+
+const KINDS: Record<string, string> = {
+  feature: "New capability or behaviour",
+  bugfix: "Existing behaviour was wrong and is fixed",
+  refactor: "Restructures code without changing behaviour",
+  tests: "Adds or fixes tests only",
+  docs: "Documentation only",
+  dependency: "Upgrades or changes dependencies",
+  chore: "Configuration, build, tooling or cleanup",
+};
+
+/** The pull request as Jev reads it. */
+export interface PullInput {
+  title: string;
+  body: string;
+  /** Changed files with their line counts, e.g. `src/a.ts (+12 −3)`. */
+  files: readonly string[];
+  diff: string;
+}
+
+/** What Jev made of a pull request. */
+export interface PullRead {
+  size: TriageSize;
+  sizeConfidence: number;
+  /** Probabilities of yes, 0 to 1. */
+  risky: number;
+  breaking: number;
+  security: number;
+  testsMissing: number;
+  kind?: string;
+  kindProbability?: number;
+  model: string;
+  ms: number;
+}
+
+/** Characters of diff sent: the rest is what the agent's review is for. */
+export const READ_DIFF_CHARS = 80_000;
+
+export function pullRequest(input: PullInput): SystemOneRequest {
+  return {
+    state: {
+      title: clip(input.title, 300),
+      description: clip(input.body, 3000),
+      changed_files: clip(input.files.join("\n"), 4000),
+      diff: clip(input.diff, READ_DIFF_CHARS),
+    },
+    questions: {
+      size: score("How big is the change in `diff`, judged by what it would take to review and verify?", SIZE_LEVELS),
+      risky: noul(
+        "Could merging `diff` break existing behaviour or cause harm: data loss, corrupted state, wrong results, concurrency bugs, performance cliffs, or an outage?",
+        "Yes: there is a plausible way this breaks something that works today.",
+        "No: it is low-risk, well contained, or purely additive.",
+      ),
+      breaking: noul(
+        "Does `diff` change a public API, a config or file format, a database schema or a command-line interface in a way that breaks existing callers or users?",
+        "Yes: something outside this change has to adapt.",
+        "No: existing callers and data keep working as they are.",
+      ),
+      security: noul(
+        "Does `diff` touch authentication, authorisation, secrets, input validation, cryptography, or other security-sensitive code?",
+        "Yes: a mistake here could be a vulnerability.",
+        "No: nothing in it is security-relevant.",
+      ),
+      tests_missing: noul(
+        "Does `diff` change behaviour without adding or updating tests that cover the change?",
+        "Yes: the behaviour changes and no test in the diff covers it.",
+        "No: it adds or updates tests for what it changes, or it changes no behaviour.",
+      ),
+      kind: choice("What kind of change is `diff`?", KINDS),
+    },
+  };
+}
+
+/** Jev's read of a pull request, or undefined when the classifier is off or fails. */
+export async function readPull(classifier: Classifier, input: PullInput, signal?: AbortSignal): Promise<PullRead | undefined> {
+  if (!classifier.enabled("review")) return undefined;
+  const result = await classifier.ask("review", pullRequest(input), signal ? { signal } : {});
+  if (!result) return undefined;
+  const size = scoreOf(result.answers, "size");
+  if (!size) return undefined;
+  const kind = choiceOf(result.answers, "kind");
+  return {
+    size: TRIAGE_SIZES[Math.max(0, Math.min(TRIAGE_SIZES.length - 1, size.level))]!,
+    sizeConfidence: size.confidence,
+    risky: yesOf(result.answers, "risky") ?? 0,
+    breaking: yesOf(result.answers, "breaking") ?? 0,
+    security: yesOf(result.answers, "security") ?? 0,
+    testsMissing: yesOf(result.answers, "tests_missing") ?? 0,
+    ...(kind ? { kind: kind.choice, kindProbability: kind.probability } : {}),
+    model: result.model,
+    ms: result.ms,
+  };
+}
+
+const CONCERN = 0.5;
+
+/** The concerns worth a look, most likely first, as words. */
+export function concerns(read: PullRead): string[] {
+  const found: Array<[number, string]> = [
+    [read.risky, "risky"],
+    [read.security, "touches security"],
+    [read.breaking, "may break callers"],
+    [read.testsMissing, "no tests for the change"],
+  ];
+  return found.filter(([probability]) => probability >= CONCERN).sort((a, b) => b[0] - a[0]).map(([, words]) => words);
+}
+
+/** Whether a full review by an agent is worth its tokens: a concern, or a change too big to skim. */
+export function worthReview(read: PullRead): boolean {
+  return concerns(read).length > 0 || read.size === "large";
+}
+
+/** One line: `medium · bugfix · risky 0.71, no tests for the change 0.64 → worth a full review`. */
+export function readLine(read: PullRead): string {
+  const kind = read.kind ? ` · ${read.kind}` : "";
+  const flagged = concerns(read);
+  const figures = [
+    ["risky", read.risky],
+    ["security", read.security],
+    ["breaking", read.breaking],
+    ["tests missing", read.testsMissing],
+  ] as const;
+  const detail = flagged.length > 0
+    ? figures.filter(([, probability]) => probability >= CONCERN).sort((a, b) => b[1] - a[1]).map(([name, probability]) => `${name} ${probability.toFixed(2)}`).join(", ")
+    : "nothing stands out";
+  return `${read.size}${kind} · ${detail} → ${worthReview(read) ? "worth a full review" : "looks routine"}`;
+}

package/src/execution/agent-runner.ts

@@ -7,6 +7,7 @@ import { shortDuration, truncate } from "../text.ts";
 import { EditLog } from "../state/changes.ts";
 import { formatMinutes, REPORT_GRACE_MS } from "../state/budget.ts";
 import { runPiAgent, spawnPiProcess, type PiStreamEvent, type ProcessRunner, type RelayAsk } from "./pi-runner.ts";
+import { isUnavailable, looksUnavailable, markUnavailable, usableFallback } from "./fallback.ts";
 import { ASK_ENV } from "../ask/relay.ts";
 import { ASK_TOOL } from "../ask/types.ts";
 
@@ -40,6 +41,10 @@ export interface AgentRequest {
   context: AgentContext;
   model?: string;
   thinking?: string;
+  /** Where the run goes when its model runs out of usage or is unavailable. */
+  fallback?: { model: string; thinking: string };
+  /** Set by the runner once it has switched: the model that ran out. */
+  fellBackFrom?: string;
   timeoutMs: number;
   cwd: string;
   signal?: AbortSignal;
@@ -135,13 +140,24 @@ function retryable(run: AgentRun): boolean {
  */
 export async function runAgent(request: AgentRequest, run: ProcessRunner = spawnPiProcess): Promise<AgentRun> {
   const startedAt = new Date().toISOString();
-  const attempts = Math.max(1, (request.retries ?? 0) + 1);
+  let attempts = Math.max(1, (request.retries ?? 0) + 1);
   // A failed attempt may have edited files before the retry: the run owns every edit.
   const edits = new EditLog(request.cwd);
   let last: AgentRun | undefined;
+  // A model already known to be out of usage goes straight to the fallback.
+  const other = usableFallback(request.fallback, request.model);
+  if (other && isUnavailable(request.model)) request = switchToFallback(request, other, request.model ?? "the session model");
   for (let attempt = 1; attempt <= attempts; attempt++) {
     last = await runAgentOnce(request, run, attempt, startedAt, edits);
     request.onAttemptEnd?.(last);
+    // Out of usage (or the model unavailable): the same model would fail again, so the fallback takes the retry.
+    const fallback = usableFallback(request.fallback, request.model);
+    if (fallback && !request.fellBackFrom && last.status === "failed" && looksUnavailable(last.error)) {
+      if (request.model) markUnavailable(request.model);
+      request = switchToFallback(request, fallback, request.model ?? "the session model");
+      attempts += 1;
+      continue;
+    }
     if (!retryable(last)) break;
     // Under a budget a retry only uses what is left of the allotment.
     if (request.time && request.time.endsAt - Date.now() < MIN_ATTEMPT_MS) break;
@@ -150,6 +166,11 @@ export async function runAgent(request: AgentRequest, run: ProcessRunner = spawn
   return edited.length > 0 ? { ...last!, edited } : last!;
 }
 
+/** The request moved to its fallback model and thinking level. */
+function switchToFallback(request: AgentRequest, fallback: { model: string; thinking?: string }, from: string): AgentRequest {
+  return { ...request, model: fallback.model, thinking: fallback.thinking ?? request.thinking, fellBackFrom: from };
+}
+
 /** Abort every in-flight subagent (session shutdown, user cancel). */
 export function cancelAllRuns(): void {
   for (const controller of activeControllers) controller.abort();
@@ -168,6 +189,7 @@ function baseRun(request: AgentRequest, runId: string, startedAt: string, attemp
     attempts,
     startedAt,
     ...(request.thinking ? { thinking: request.thinking } : {}),
+    ...(request.fellBackFrom ? { fellBackFrom: request.fellBackFrom } : {}),
     ...(request.routedFrom ? { routedFrom: request.routedFrom } : {}),
     ...(request.route ? { route: request.route } : {}),
     ...(request.time ? { allotMs: request.time.allotMs, endsAt: request.time.endsAt } : {}),

package/src/execution/fallback.ts

@@ -0,0 +1,75 @@
+/**
+ * Fallback models. A subscription or key that runs out mid-task (a usage
+ * limit, a rate limit, no credit, the provider down or refusing the key)
+ * fails every run on that model the same way, so the run goes to the agent's
+ * configured fallback model instead, and the exhausted model is skipped for a
+ * while so the next agents do not each spend a failed run finding out.
+ */
+
+/** What a provider says when a model cannot be used right now. Deliberately narrow: an ordinary failure is not a reason to switch model. */
+const UNAVAILABLE = [
+  /usage limit/i, /rate.?limit/i, /\bquota\b/i, /limit (?:reached|exceeded|will reset)/i, /exceeded (?:your|the|current)/i,
+  /out of (?:usage|credits?|extra usage|tokens)/i, /(?:insufficient|no) (?:credits?|funds|balance|quota)/i, /credit balance/i,
+  /billing/i, /payment required/i, /\b402\b/, /\b429\b/, /too many requests/i, /resource.?exhausted/i,
+  /overloaded/i, /\b529\b/, /(?:at|over) capacity/i, /resets? (?:at|in|on)/i, /subscription/i,
+  /unauthori[sz]ed/i, /\b401\b/, /invalid (?:api )?key/i, /no api key/i, /authentication (?:failed|error)/i,
+  /model (?:is )?(?:not found|not available|unavailable)/i, /unknown model/i, /does not have access/i,
+];
+
+/** True when a failed run's error says its model is out of usage or unavailable, so another model may succeed. */
+export function looksUnavailable(error: string | undefined): boolean {
+  return Boolean(error && UNAVAILABLE.some((pattern) => pattern.test(error)));
+}
+
+/** How long a model that ran out is skipped before it is tried again. */
+export const COOLDOWN_MS = 20 * 60 * 1000;
+
+const exhausted = new Map<string, number>();
+
+/** Remember that `model` cannot be used until the cooldown passes. */
+export function markUnavailable(model: string, now = Date.now()): void {
+  exhausted.set(model, now + COOLDOWN_MS);
+}
+
+/** Whether `model` ran out recently enough to skip. */
+export function isUnavailable(model: string | undefined, now = Date.now()): boolean {
+  if (!model) return false;
+  const until = exhausted.get(model);
+  if (until === undefined) return false;
+  if (until <= now) {
+    exhausted.delete(model);
+    return false;
+  }
+  return true;
+}
+
+/** Forget every exhausted model (tests). */
+export function resetUnavailable(): void {
+  exhausted.clear();
+}
+
+/** A fallback worth switching to: a model other than the one that failed. */
+export function usableFallback<F extends { model: string }>(fallback: F | undefined, current: string | undefined): F | undefined {
+  return fallback && fallback.model !== current ? fallback : undefined;
+}
+
+/**
+ * Run `attempt` on `model`; when it fails because that model is out of usage
+ * or unavailable, run it again on the fallback. A model already known to be
+ * out goes straight to the fallback. `switched` says which model took over.
+ */
+export async function withFallback<T extends { status: string; error?: string }>(
+  model: string | undefined,
+  thinking: string,
+  fallback: { model: string; thinking: string } | undefined,
+  attempt: (model: string | undefined, thinking: string) => Promise<T>,
+): Promise<{ result: T; switchedFrom?: string }> {
+  const other = usableFallback(fallback, model);
+  if (other && isUnavailable(model)) return { result: await attempt(other.model, other.thinking), switchedFrom: model ?? "the session model" };
+  const result = await attempt(model, thinking);
+  if (other && result.status === "failed" && looksUnavailable(result.error)) {
+    if (model) markUnavailable(model);
+    return { result: await attempt(other.model, other.thinking), switchedFrom: model ?? "the session model" };
+  }
+  return { result };
+}