@stage-labs/metro 0.1.0-beta.251 → 0.1.0-beta.253

package/runtime/node_modules/@metro-labs/daemon/src/gateway/gateway.ts

@@ -1,4 +1,4 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
 import { errMsg, log } from '@metro-labs/core/log';
 import { cameThroughProxy } from '@metro-labs/http/api-http';
 import { agentIdForKey } from '../agents/keys.js';
@@ -10,7 +10,21 @@ import {
   freshAdaptations,
   type Adaptations,
 } from './bedrock.js';
-import { addBeta, anthropicHeaders, forwardedHeaders, GatewayError, parseJson, pipeResponse, readBody, sendError, upstreamMessage, watchUpstream } from './forward.js';
+import {
+  addBeta,
+  anthropicHeaders,
+  forwardedHeaders,
+  GatewayError,
+  holdLimitRefusal,
+  loginHeaders,
+  parseJson,
+  pipeResponse,
+  readBody,
+  sendError,
+  upstreamMessage,
+  watchUpstream,
+} from './forward.js';
+import { chainOf, forgetFallbackState, noteChoice, noteRefused, routesToTry } from './fallback.js';
 import {
   BINDING_BETA,
   cappedEffort,
@@ -37,6 +51,7 @@ import { forgetUsage, noteUsageHeaders, UsageScanner } from './usage.js';
 import { fitToolSearch } from './tool-search.js';
 import { ANTHROPIC_API, refreshLoginModels } from './provider-models.js';
 import type { CodexTokens } from './codex-auth.js';
+import { forgetClaudeTokens, withClaudeLogin, type ClaudeLoginDeps } from './claude-logins.js';
 
 const GATEWAY_PREFIX = '/gateway';
 const MESSAGES = '/v1/messages';
@@ -52,18 +67,21 @@ export interface GatewayDeps {
   openrouterBase?: string;
   codex?: Partial<CodexDeps>;
   gemini?: Partial<GeminiDeps>;
+  claudeLogins?: ClaudeLoginDeps;
 }
 
 const learned: Adaptations = freshAdaptations();
 
 export function resetGatewayState(): void {
   forgetServed();
+  forgetFallbackState();
   forgetUsage();
   learned.fields.clear();
   learned.dropBetas = false;
   forgetLearnedThinking();
   sharedCodexState.clear();
   sharedGeminiState.clear();
+  forgetClaudeTokens();
 }
 
 const saveCodexTokens = (id: string, tokens: CodexTokens): void => {
@@ -88,7 +106,18 @@ function modelsBody(cfg: ModelConfig): Record<string, unknown> {
   return { data, has_more: false, first_id: data[0]?.id ?? null, last_id: data.at(-1)?.id ?? null };
 }
 
-const PASSTHROUGH: Connection = { id: PASSTHROUGH_ID, provider: 'anthropic', label: 'Claude Code login', model: '', apiKey: '', region: '', zdr: false, codex: null, gemini: null };
+const PASSTHROUGH: Connection = {
+  id: PASSTHROUGH_ID,
+  provider: 'anthropic',
+  label: 'Claude Code login',
+  model: '',
+  apiKey: '',
+  region: '',
+  zdr: false,
+  codex: null,
+  gemini: null,
+  claude: null,
+};
 
 const passthrough = (body: Record<string, unknown>): Route => ({ connection: PASSTHROUGH, model: requestedModel(body) });
 
@@ -137,12 +166,27 @@ async function refusedThinkingOff(upstream: Response, shaped: Record<string, unk
   return true;
 }
 
-function listLoginModels(req: IncomingMessage, anthropicBase: string): void {
-  refreshLoginModels(req.headers, anthropicBase).catch((err: unknown) => {
+function listLoginModels(headers: IncomingHttpHeaders, anthropicBase: string): void {
+  refreshLoginModels(headers, anthropicBase).catch((err: unknown) => {
     log.warn({ err: errMsg(err) }, 'gateway: could not list the models of the Claude Code login');
   });
 }
 
+function sendAnthropic(req: IncomingMessage, conn: Connection, anthropicBase: string, attempt: (base: Record<string, string>) => Promise<Response>, deps: GatewayDeps): Promise<Response> {
+  if (conn.apiKey !== '') return attempt(anthropicHeaders(req, conn.apiKey));
+  if (conn.claude === null) return attempt(forwardedHeaders(req));
+  return withClaudeLogin(conn.claude.id, deps.claudeLogins ?? {}, (token) => {
+    listLoginModels({ authorization: `Bearer ${token}` }, anthropicBase);
+    return attempt(loginHeaders(req, token));
+  });
+}
+
+async function refusedLogin(conn: Connection, upstream: Response): Promise<void> {
+  if (conn.apiKey !== '' || conn.claude === null || upstream.status !== 401) return;
+  await upstream.body?.cancel();
+  throw new GatewayError(403, 'permission_error', `Anthropic refused the Claude login of ${conn.label}: sign in again on the Model page`);
+}
+
 async function toAnthropic(
   req: IncomingMessage,
   res: ServerResponse,
@@ -155,25 +199,28 @@ async function toAnthropic(
   const conn = route.connection;
   const anthropicBase = deps.anthropicBase ?? ANTHROPIC_API;
   const url = `${anthropicBase}${(req.url ?? '').slice(GATEWAY_PREFIX.length)}`;
-  const key = conn.apiKey;
-  if (key === '' && standsInFor(req))
+  const passthrough = conn.apiKey === '' && conn.claude === null;
+  if (passthrough && standsInFor(req))
     throw new GatewayError(
       403,
       'permission_error',
       'Claude Code on this machine has no Anthropic login of its own; choose Bedrock, OpenRouter, Codex or Gemini on the Model page, or sign in on the Claude tab',
     );
   const watch = watchUpstream(res);
-  if (key === '') listLoginModels(req, anthropicBase);
-  const base = key === '' ? forwardedHeaders(req) : anthropicHeaders(req, key);
+  if (passthrough) listLoginModels(req.headers, anthropicBase);
   const send = (payload: Buffer, headers: Record<string, string>): Promise<Response> =>
     fetch(url, { method: 'POST', headers, body: new Uint8Array(payload), signal: watch.signal, redirect: 'manual' });
-  const attempt = (): Promise<Response> => asAnthropicWants(send, base, anthropicPayloads(raw, sent, shaped, route.model), conn.label, route.model);
-  const first = await attempt();
-  const upstream = (await refusedThinkingOff(first, shaped, route.model)) ? await attempt() : first;
+  const attempt = async (base: Record<string, string>): Promise<Response> => {
+    const shape = (): Promise<Response> => asAnthropicWants(send, base, anthropicPayloads(raw, sent, shaped, route.model), conn.label, route.model);
+    const first = await shape();
+    return (await refusedThinkingOff(first, shaped, route.model)) ? shape() : first;
+  };
+  const upstream = await sendAnthropic(req, conn, anthropicBase, attempt, deps);
+  await refusedLogin(conn, upstream);
   noteRefusal(conn.label, route.model, upstream);
   noteUsageHeaders('anthropic', conn.id, upstream.headers);
   const scanner = new UsageScanner(conn.id);
-  await pipeResponse(upstream, res, watch, key === '' ? { scanner } : { ownCredential: true, scanner });
+  await pipeResponse(upstream, res, watch, passthrough ? { scanner } : { ownCredential: true, scanner });
 }
 
 async function toOpenRouter(
@@ -237,13 +284,17 @@ function shapedFor(req: IncomingMessage, sent: Record<string, unknown>): Record<
 
 const bytesOf = (raw: Buffer, parsed: Record<string, unknown>, sent: Record<string, unknown>): Buffer => (sent === parsed ? raw : Buffer.from(JSON.stringify(sent)));
 
-async function dispatch(req: IncomingMessage, res: ServerResponse, path: string, deps: GatewayDeps): Promise<void> {
-  const cfg = deps.config();
-  const raw = await readBody(req);
-  const parsed = parseJson(raw);
-  const sent = fitToolSearch(req, parsed);
-  const route = resolveRoute(requestedModel(sent), cfg) ?? passthrough(sent);
-  const body = shapedFor(req, sent);
+interface Request {
+  path: string;
+  raw: Buffer;
+  parsed: Record<string, unknown>;
+  sent: Record<string, unknown>;
+  body: Record<string, unknown>;
+  cfg: ModelConfig;
+}
+
+async function attempt(req: IncomingMessage, res: ServerResponse, ask: Request, route: Route, deps: GatewayDeps): Promise<void> {
+  const { path, body } = ask;
   const conn = route.connection;
   log.info({ route: routeLabel(route), connection: conn.label, path }, 'gateway: routing');
   if (path === MESSAGES) noteServed({ connection: conn.id, provider: conn.provider, model: route.model, at: new Date().toISOString() });
@@ -256,14 +307,38 @@ async function dispatch(req: IncomingMessage, res: ServerResponse, path: string,
   }
   if (conn.provider === 'openrouter') {
     if (path === COUNT) throw new GatewayError(404, 'not_found_error', 'OpenRouter does not count tokens');
-    await toOpenRouter(req, res, body, route, cfg, deps);
+    await toOpenRouter(req, res, body, route, ask.cfg, deps);
     return;
   }
   if (conn.provider === 'codex' || conn.provider === 'gemini') {
     await toSubscription(req, res, path, body, route, deps);
     return;
   }
-  await toAnthropic(req, res, bytesOf(raw, parsed, sent), sent, body, route, deps);
+  await toAnthropic(req, res, bytesOf(ask.raw, ask.parsed, ask.sent), ask.sent, body, route, deps);
+}
+
+async function dispatch(req: IncomingMessage, res: ServerResponse, path: string, deps: GatewayDeps): Promise<void> {
+  const cfg = deps.config();
+  const raw = await readBody(req);
+  const parsed = parseJson(raw);
+  const sent = fitToolSearch(req, parsed);
+  const requested = requestedModel(sent);
+  const primary = resolveRoute(requested, cfg) ?? passthrough(sent);
+  const ask: Request = { path, raw, parsed, sent, body: shapedFor(req, sent), cfg };
+  const routes = routesToTry(chainOf(primary, cfg, requested));
+  for (const [at, route] of routes.entries()) {
+    const next = routes[at + 1];
+    if (path === MESSAGES) noteChoice(primary, route);
+    if (next === undefined) {
+      await attempt(req, res, ask, route, deps);
+      return;
+    }
+    const held = holdLimitRefusal(res);
+    await attempt(req, held.res, ask, route, deps);
+    const refusal = held.refusal();
+    if (refusal === null) return;
+    noteRefused(route, refusal.status, refusal.headers, next);
+  }
 }
 
 function failed(res: ServerResponse, err: unknown): void {

package/runtime/node_modules/@metro-labs/daemon/src/gateway/model-api.ts

@@ -14,17 +14,20 @@ import {
   parseModelConfig,
   readModelConfig,
   removeConnection,
+  setFallbacks,
   setRoute,
   updateConnection,
   writeModelConfig,
   type ModelConfig,
 } from './model-config.js';
-import { asApiError, BODY_MAX, connectionFor, settingsBody, type ModelApiDeps, type Route, type Store } from './model-store.js';
+import { asApiError, BODY_MAX, claudeLoginDeps, connectionFor, settingsBody, type ModelApiDeps, type Route, type Store } from './model-store.js';
+import { dropUnusedClaudeLogins } from './claude-logins.js';
 import { CODEX_ROUTES, codexDeviceRoute, GEMINI_ROUTES } from './model-signin.js';
 import { refreshUsage } from './usage-refresh.js';
 
 const PATH = '/api/model';
 const CONNECTIONS = '/api/model/connections';
+const FALLBACKS = '/api/model/fallbacks';
 const CODEX = '/api/model/codex/';
 const GEMINI = '/api/model/gemini/';
 const OPENROUTER = '/api/model/openrouter/';
@@ -69,6 +72,11 @@ async function chooseRoute(req: IncomingMessage, deps: ModelApiDeps, store: Stor
   return kept(store, next, deps, 'model-api: route changed', { route: next.route });
 }
 
+async function chooseFallbacks(req: IncomingMessage, deps: ModelApiDeps, store: Store): Promise<unknown> {
+  const next = await withBody(req, (body) => setFallbacks(store.read(), body.fallbacks));
+  return kept(store, next, deps, 'model-api: fallback models changed', { fallbacks: (next.fallbacks ?? []).map((f) => `${f.connection}:${f.model}`) });
+}
+
 async function create(req: IncomingMessage, deps: ModelApiDeps, store: Store): Promise<unknown> {
   const next = await withBody(req, (body) => addConnection(store.read(), body));
   return kept(store, next, deps, 'model-api: connection added', { connection: next.connections.at(-1)?.id ?? '' });
@@ -82,14 +90,17 @@ async function change(req: IncomingMessage, deps: ModelApiDeps, store: Store, id
 }
 
 function drop(deps: ModelApiDeps, store: Store, id: string): unknown {
+  const before = store.read();
   let next: ModelConfig;
   try {
-    next = removeConnection(store.read(), id);
+    next = removeConnection(before, id);
   } catch (err) {
     asApiError(err);
   }
   forgetOne(id);
-  return kept(store, next, deps, 'model-api: connection removed', { connection: id });
+  const body = kept(store, next, deps, 'model-api: connection removed', { connection: id });
+  dropUnusedClaudeLogins(before, next, claudeLoginDeps(deps));
+  return body;
 }
 
 async function settingsWithUsage(deps: ModelApiDeps, store: Store): Promise<Record<string, unknown>> {
@@ -125,7 +136,11 @@ const named = (table: Record<string, Route>, name: string, method: string | unde
 async function restore(req: IncomingMessage, store: Store, deps: ModelApiDeps): Promise<unknown> {
   const body = await readJsonBody(req, RESTORE_MAX);
   if (!isRecord(body)) throw new ApiError('body must be a JSON object', 400);
-  return kept(store, parseModelConfig(body), deps, 'model-api: model setup restored from a file', {});
+  const before = store.read();
+  const next = parseModelConfig(body);
+  const answer = kept(store, next, deps, 'model-api: model setup restored from a file', {});
+  dropUnusedClaudeLogins(before, next, claudeLoginDeps(deps));
+  return answer;
 }
 
 function bundleRoute(path: string, method: string | undefined): Route | number {
@@ -133,7 +148,8 @@ function bundleRoute(path: string, method: string | undefined): Route | number {
   return method === 'POST' ? { method: 'POST', run: (req, deps, store) => restore(req, store, deps) } : 405;
 }
 
-function settingsRoute(method: string | undefined): Route | number {
+function settingsRoute(path: string, method: string | undefined): Route | number {
+  if (path === FALLBACKS) return method === 'PUT' ? { method: 'POST', run: chooseFallbacks } : 405;
   if (method === 'GET') return { method: 'GET', run: (_req, deps, store) => settingsWithUsage(deps, store) };
   if (method === 'PUT') return { method: 'POST', run: chooseRoute };
   return 405;
@@ -155,26 +171,23 @@ function codexRoute(rest: string, method: string | undefined): Route | number {
   return codexDeviceRoute(id, method);
 }
 
-const mine = (path: string): boolean =>
-  path === PATH ||
-  path === BUNDLE ||
-  path === RESTORE ||
-  path === CONNECTIONS ||
-  path.startsWith(`${CONNECTIONS}/`) ||
-  path.startsWith(CODEX) ||
-  path.startsWith(GEMINI) ||
-  path.startsWith(OPENROUTER) ||
-  path.startsWith(ANTHROPIC) ||
-  path.startsWith(BEDROCK);
+const TABLES: [string, Record<string, Route>][] = [
+  [OPENROUTER, OPENROUTER_ROUTES],
+  [ANTHROPIC, ANTHROPIC_ROUTES],
+  [BEDROCK, BEDROCK_ROUTES],
+  [GEMINI, GEMINI_ROUTES],
+];
+const EXACT = new Set([PATH, FALLBACKS, BUNDLE, RESTORE, CONNECTIONS]);
+const PREFIXES = [`${CONNECTIONS}/`, CODEX, ...TABLES.map(([prefix]) => prefix)];
+
+const mine = (path: string): boolean => EXACT.has(path) || PREFIXES.some((prefix) => path.startsWith(prefix));
 
 function routeFor(path: string, method: string | undefined): Route | number {
-  if (path === PATH) return settingsRoute(method);
+  if (path === PATH || path === FALLBACKS) return settingsRoute(path, method);
   if (path === BUNDLE || path === RESTORE) return bundleRoute(path, method);
   if (path === CONNECTIONS || path.startsWith(`${CONNECTIONS}/`)) return connectionsRoute(path, method);
-  if (path.startsWith(OPENROUTER)) return named(OPENROUTER_ROUTES, path.slice(OPENROUTER.length), method);
-  if (path.startsWith(ANTHROPIC)) return named(ANTHROPIC_ROUTES, path.slice(ANTHROPIC.length), method);
-  if (path.startsWith(BEDROCK)) return named(BEDROCK_ROUTES, path.slice(BEDROCK.length), method);
-  if (path.startsWith(GEMINI)) return named(GEMINI_ROUTES, path.slice(GEMINI.length), method);
+  const table = TABLES.find(([prefix]) => path.startsWith(prefix));
+  if (table !== undefined) return named(table[1], path.slice(table[0].length), method);
   return codexRoute(path.slice(CODEX.length), method);
 }
 

package/runtime/node_modules/@metro-labs/daemon/src/gateway/model-config.ts

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { newId } from '@metro-labs/core/ids';
+import { ID_RE, newId } from '@metro-labs/core/ids';
 import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
 import { agentsDir } from '../agents/files.js';
 import { isRecord } from '@metro-labs/core/is-record';
@@ -9,6 +9,13 @@ import { tokensFromDisk as geminiTokensFromDisk, type GeminiTokens } from './gem
 export const PROVIDERS = ['anthropic', 'bedrock', 'openrouter', 'codex', 'gemini'] as const;
 export type Provider = (typeof PROVIDERS)[number];
 
+export interface ClaudeLogin {
+  id: string;
+  email: string | null;
+  plan: string | null;
+  savedAt: string;
+}
+
 export interface Connection {
   id: string;
   provider: Provider;
@@ -19,12 +26,19 @@ export interface Connection {
   zdr: boolean;
   codex: CodexTokens | null;
   gemini: GeminiTokens | null;
+  claude: ClaudeLogin | null;
+}
+
+export interface Fallback {
+  connection: string;
+  model: string;
 }
 
 export interface ModelConfig {
   version: 2;
   route: string;
   connections: Connection[];
+  fallbacks?: Fallback[];
 }
 
 export interface Route {
@@ -38,6 +52,7 @@ const MODEL_FILE = 'model.json';
 const MAX_FIELD = 512;
 const MAX_LABEL = 60;
 const MAX_CONNECTIONS = 20;
+const MAX_FALLBACKS = 8;
 const PREFIX_RE = /^(anthropic|bedrock|openrouter|codex|gemini):(.+)$/;
 const SMALL_RE = /haiku/i;
 
@@ -66,8 +81,14 @@ const newConnection = (provider: Provider, label: string): Connection => ({
   zdr: false,
   codex: null,
   gemini: null,
+  claude: null,
 });
 
+function claudeFromDisk(raw: unknown): ClaudeLogin | null {
+  if (!isRecord(raw) || !ID_RE.test(text(raw.id))) return null;
+  return { id: text(raw.id), email: maybe(raw.email), plan: maybe(raw.plan), savedAt: text(raw.savedAt) };
+}
+
 function codexFromDisk(raw: unknown): CodexTokens | null {
   if (!isRecord(raw)) return null;
   const accessToken = text(raw.accessToken);
@@ -99,14 +120,33 @@ function connectionFromDisk(raw: unknown): Connection | null {
     zdr: raw.zdr === true,
     codex: codexFromDisk(raw.codex),
     gemini: geminiTokensFromDisk(raw.gemini),
+    claude: provider === 'anthropic' ? claudeFromDisk(raw.claude) : null,
   };
 }
 
+function fallbacksOf(raw: unknown, connections: Connection[]): Fallback[] {
+  if (!Array.isArray(raw)) return [];
+  const known = raw.flatMap((f: unknown) => {
+    if (!isRecord(f)) return [];
+    const entry = { connection: text(f.connection), model: text(f.model).slice(0, MAX_FIELD) };
+    return entry.model !== '' && connections.some((c) => c.id === entry.connection) ? [entry] : [];
+  });
+  return known.filter((f, at) => known.findIndex((o) => o.connection === f.connection && o.model === f.model) === at).slice(0, MAX_FALLBACKS);
+}
+
+const withFallbacks = (cfg: ModelConfig, fallbacks: Fallback[]): ModelConfig => ({
+  version: 2,
+  route: cfg.route,
+  connections: cfg.connections,
+  ...(fallbacks.length === 0 ? {} : { fallbacks }),
+});
+
 export function parseModelConfig(raw: unknown): ModelConfig {
   if (!isRecord(raw) || !Array.isArray(raw.connections)) return empty();
   const connections = raw.connections.flatMap((c: unknown) => connectionFromDisk(c) ?? []).slice(0, MAX_CONNECTIONS);
   const route = text(raw.route);
-  return { version: 2, route: connections.some((c) => c.id === route) ? route : (connections[0]?.id ?? ''), connections };
+  const cfg: ModelConfig = { version: 2, route: connections.some((c) => c.id === route) ? route : (connections[0]?.id ?? ''), connections };
+  return withFallbacks(cfg, fallbacksOf(raw.fallbacks, connections));
 }
 
 const needsIds = (raw: unknown): boolean =>
@@ -160,7 +200,7 @@ export function notReady(cfg: ModelConfig, conn = routedConnection(cfg)): string
   return CHECKS[conn.provider].find(([missing]) => missing(conn))?.[1] ?? null;
 }
 
-const isSmallModel = (requested: string): boolean => SMALL_RE.test(requested);
+export const isSmallModel = (requested: string): boolean => SMALL_RE.test(requested);
 
 const DEFAULTS: Record<Provider, (requested: string, c: Connection) => string> = {
   openrouter: (requested, c) => (requested.includes('/') ? requested : c.model),
@@ -176,6 +216,8 @@ function forProvider(cfg: ModelConfig, provider: Provider): Connection | null {
   return cfg.connections.find((c) => c.provider === provider) ?? null;
 }
 
+export const bareModel = (requested: string): string => PREFIX_RE.exec(requested)?.[2]?.trim() ?? requested;
+
 export function resolveRoute(requested: string, cfg: ModelConfig): Route | null {
   const explicit = PREFIX_RE.exec(requested);
   if (explicit !== null && isProvider(explicit[1])) {
@@ -192,6 +234,7 @@ export const routeLabel = (route: Route): string =>
 export const PASSTHROUGH_ID = 'passthrough';
 
 function signedInAs(c: Connection): { account: string | null; plan: string | null } {
+  if (c.claude !== null) return { account: c.claude.email, plan: c.claude.plan };
   if (c.codex === null) return { account: c.gemini?.email ?? null, plan: c.gemini?.tier ?? null };
   const claims = claimsOf(c.codex.idToken);
   return { account: c.codex.email ?? claims.email, plan: c.codex.plan ?? claims.plan };
@@ -206,7 +249,7 @@ function publicConnection(c: Connection): Record<string, unknown> {
     hasKey: c.apiKey !== '',
     region: c.region,
     zdr: c.zdr,
-    signedIn: c.codex !== null || c.gemini !== null,
+    signedIn: c.codex !== null || c.gemini !== null || c.claude !== null,
     ...signedInAs(c),
   };
 }
@@ -227,6 +270,9 @@ export const setCodexAuth = (cfg: ModelConfig, id: string, auth: CodexTokens | n
 export const setGeminiAuth = (cfg: ModelConfig, id: string, auth: GeminiTokens | null): ModelConfig =>
   withConnection(cfg, id, (c) => ({ ...c, gemini: auth }));
 
+export const setClaudeLogin = (cfg: ModelConfig, id: string, login: ClaudeLogin | null): ModelConfig =>
+  withConnection(cfg, id, (c) => ({ ...c, claude: login }));
+
 function field(patch: Record<string, unknown>, key: string, current: string, what: string, max = MAX_FIELD): string {
   if (!(key in patch)) return current;
   const value = patch[key];
@@ -276,7 +322,24 @@ export function updateConnection(cfg: ModelConfig, id: string, patch: unknown):
 export function removeConnection(cfg: ModelConfig, id: string): ModelConfig {
   requireConnection(cfg, id);
   const connections = cfg.connections.filter((c) => c.id !== id);
-  return { ...cfg, route: cfg.route === id ? (connections[0]?.id ?? '') : cfg.route, connections };
+  const next = { ...cfg, route: cfg.route === id ? (connections[0]?.id ?? '') : cfg.route, connections };
+  return withFallbacks(next, (cfg.fallbacks ?? []).filter((f) => f.connection !== id));
+}
+
+function fallbackEntry(cfg: ModelConfig, raw: unknown): Fallback {
+  if (!isRecord(raw)) throw new ModelConfigError('each fallback must be an object with a connection and a model');
+  const connection = field(raw, 'connection', '', 'connection');
+  const model = field(raw, 'model', '', 'model');
+  requireConnection(cfg, connection);
+  if (model === '') throw new ModelConfigError('each fallback needs a model');
+  return { connection, model };
+}
+
+export function setFallbacks(cfg: ModelConfig, raw: unknown): ModelConfig {
+  if (!Array.isArray(raw)) throw new ModelConfigError('fallbacks must be a list');
+  if (raw.length > MAX_FALLBACKS) throw new ModelConfigError(`a box keeps at most ${String(MAX_FALLBACKS)} fallbacks`);
+  const entries = raw.map((f: unknown) => fallbackEntry(cfg, f));
+  return withFallbacks(cfg, fallbacksOf(entries, cfg.connections));
 }
 
 export function setRoute(cfg: ModelConfig, id: string): ModelConfig {

package/runtime/node_modules/@metro-labs/daemon/src/gateway/model-signin.ts

@@ -42,6 +42,8 @@ const saved = (store: Store, cfg: ModelConfig, note: string, fields: { connectio
 
 function keepCodex(store: Store, req: IncomingMessage, tokens: CodexTokens | null, note: string): unknown {
   const { cfg, id } = connectionToFill(store, req, 'codex');
+  const twin = cfg.connections.find((c) => c.id !== id && tokens !== null && c.codex?.refreshToken === tokens.refreshToken);
+  if (twin !== undefined) throw new ApiError(`this ChatGPT login is already connected as ${twin.label}; sign in with ChatGPT to add another one`, 409);
   const next = setCodexAuth(cfg, id, tokens);
   return saved(store, next, note, { connection: id, plan: tokens?.plan ?? null });
 }

package/runtime/node_modules/@metro-labs/daemon/src/gateway/model-store.ts

@@ -5,8 +5,10 @@ import { GeminiAuthError } from './gemini-auth.js';
 import { GatewayError } from './forward.js';
 import { lastServed } from './served.js';
 import { usageSeen } from './usage.js';
+import { chainStatus } from './fallback.js';
 import { ModelConfigError, connectionOf, publicModelConfig, routedConnection, type Connection, type ModelConfig, type Provider } from './model-config.js';
 import type { SetupDeps } from '../claude/setup.js';
+import type { ClaudeLoginDeps } from './claude-logins.js';
 
 export interface ModelApiDeps {
   read?: () => ModelConfig;
@@ -24,10 +26,13 @@ export interface ModelApiDeps {
   bedrockControlBase?: string;
   setup?: SetupDeps;
   restartSession?: () => boolean;
-  claudeUsage?: () => Promise<unknown>;
+  claudeUsage?: (env?: Record<string, string>) => Promise<unknown>;
+  claudeLoginsRoot?: string;
   usageWaitMs?: number;
 }
 
+export const claudeLoginDeps = (deps: ModelApiDeps): ClaudeLoginDeps => ({ root: deps.claudeLoginsRoot, probe: deps.claudeUsage });
+
 export interface Store {
   read: () => ModelConfig;
   write: (cfg: ModelConfig) => void;
@@ -45,6 +50,8 @@ export const CREDITS_TTL_MS = 5 * 60_000;
 
 export const settingsBody = (cfg: ModelConfig): Record<string, unknown> => ({
   ...publicModelConfig(cfg),
+  fallbacks: cfg.fallbacks ?? [],
+  chain: chainStatus(cfg),
   lastServed: lastServed(),
   usage: usageSeen(),
 });

package/runtime/node_modules/@metro-labs/daemon/src/gateway/provider-models.ts

@@ -1,6 +1,6 @@
 import type { IncomingHttpHeaders } from 'node:http';
 import { isRecord } from '@metro-labs/core/is-record';
-import { GatewayError } from './forward.js';
+import { GatewayError, OAUTH_BETA } from './forward.js';
 import type { Connection } from './model-config.js';
 import { fingerprint, listCache } from './model-lists.js';
 import { stringOf } from '@metro-labs/http/api-http';
@@ -9,7 +9,6 @@ export const ANTHROPIC_API = 'https://api.anthropic.com';
 const ANTHROPIC_VERSION = '2023-06-01';
 const LIST_MAX = 1000;
 const LIST_TIMEOUT_MS = 10_000;
-const OAUTH_BETA = 'oauth-2025-04-20';
 const BEARER = 'Bearer ';
 
 export interface ProviderModel {

package/runtime/node_modules/@metro-labs/daemon/src/gateway/usage-refresh.ts

@@ -3,10 +3,11 @@ import { readClaudeUsage } from '../claude/usage-probe.js';
 import { codexUsageNow, sharedCodexState } from './codex.js';
 import { openrouterKey } from './openrouter.js';
 import { lastServed } from './served.js';
-import { claudeLoginUsage, geminiUsage, keepProbeAnswer, mayProbe, noteUsage, openrouterUsage, probeAnswer, usageOf, type Reported } from './usage.js';
-import { PASSTHROUGH_ID, routedConnection, type Connection, type ModelConfig } from './model-config.js';
+import { claudeLoginUsage, geminiUsage, keepProbeAnswer, mayProbe, mergeUsage, noteUsage, openrouterUsage, probeAnswer, usageOf } from './usage.js';
+import { PASSTHROUGH_ID, readModelConfig, routedConnection, writeModelConfig, type Connection, type ModelConfig } from './model-config.js';
 import { codexDepsFor, geminiModelsOf } from './model-signin.js';
-import { CREDITS_TTL_MS, type ModelApiDeps, type Store } from './model-store.js';
+import { claudeLoginDeps, CREDITS_TTL_MS, type ModelApiDeps, type Store } from './model-store.js';
+import { probeClaudeLogin } from './claude-logins.js';
 
 const WAIT_MS = 4_000;
 const LOGIN_PROBE = 'claude-login';
@@ -41,14 +42,15 @@ async function refreshCodex(conn: Connection, deps: ModelApiDeps, store: Store,
   });
 }
 
-const modelsInUse = (conn: Connection): Set<string> => {
+const modelsInUse = (conn: Connection, cfg: ModelConfig): Set<string> => {
   const served = lastServed();
-  return new Set([conn.model, served?.connection === conn.id ? served.model : ''].filter((m) => m !== ''));
+  const fallbacks = (cfg.fallbacks ?? []).filter((f) => f.connection === conn.id).map((f) => f.model);
+  return new Set([conn.model, served?.connection === conn.id ? served.model : '', ...fallbacks].filter((m) => m !== ''));
 };
 
 async function refreshQuota(conn: Connection, deps: ModelApiDeps, store: Store, now: number): Promise<void> {
   if (conn.gemini === null) return;
-  const inUse = modelsInUse(conn);
+  const inUse = modelsInUse(conn, store.read());
   const seen = usageOf(conn.id);
   const covers = seen !== undefined && [...inUse].every((id) => seen.windows.some((w) => w.label === id));
   if (seen !== undefined && covers && now - Date.parse(seen.at) < CREDITS_TTL_MS) return;
@@ -61,28 +63,38 @@ async function refreshQuota(conn: Connection, deps: ModelApiDeps, store: Store,
 
 const loginIds = (cfg: ModelConfig): string[] => [
   ...(routedConnection(cfg) === null ? [PASSTHROUGH_ID] : []),
-  ...cfg.connections.filter((c) => c.provider === 'anthropic' && c.apiKey === '').map((c) => c.id),
+  ...cfg.connections.filter((c) => c.provider === 'anthropic' && c.apiKey === '' && c.claude === null).map((c) => c.id),
 ];
 
-const olderThan = (seen: Reported | undefined, usage: Reported): boolean => seen === undefined || Date.parse(seen.at) < Date.parse(usage.at);
+const hasFallbacks = (cfg: ModelConfig): boolean => (cfg.fallbacks ?? []).length > 0;
+
+async function refreshOwnLogin(conn: Connection, cfg: ModelConfig, deps: ModelApiDeps, now: number): Promise<void> {
+  const login = conn.apiKey === '' ? conn.claude : null;
+  if (login === null || (fresh(conn.id, now) && !hasFallbacks(cfg)) || !mayProbe(conn.id, now, CREDITS_TTL_MS)) return;
+  await probe('usage of a Claude login', async () => {
+    const usage = claudeLoginUsage(await probeClaudeLogin(login.id, claudeLoginDeps(deps)), new Date(now));
+    if (usage !== null) mergeUsage(conn.id, usage);
+  });
+}
 
 async function refreshLogin(cfg: ModelConfig, deps: ModelApiDeps, now: number): Promise<void> {
-  const stale = loginIds(cfg).filter((id) => !fresh(id, now));
-  if (stale.length === 0) return;
+  const ids = loginIds(cfg);
+  if (!ids.some((id) => !fresh(id, now)) && !(hasFallbacks(cfg) && ids.length > 0)) return;
   if (mayProbe(LOGIN_PROBE, now, CREDITS_TTL_MS))
     await probe('usage of the Claude Code login', async () => {
-      const usage = claudeLoginUsage(await (deps.claudeUsage ?? readClaudeUsage)(), new Date(now));
+      const usage = claudeLoginUsage(await (deps.claudeUsage ?? (() => readClaudeUsage()))(), new Date(now));
       if (usage !== null) keepProbeAnswer(LOGIN_PROBE, usage);
     });
   const usage = probeAnswer(LOGIN_PROBE);
   if (usage === undefined || now - Date.parse(usage.at) >= CREDITS_TTL_MS) return;
-  for (const id of stale) if (olderThan(usageOf(id), usage)) noteUsage(id, usage);
+  for (const id of ids) mergeUsage(id, usage);
 }
 
-function refreshOne(conn: Connection, deps: ModelApiDeps, store: Store, now: number): Promise<void> {
+function refreshOne(conn: Connection, cfg: ModelConfig, deps: ModelApiDeps, store: Store, now: number): Promise<void> {
   if (conn.provider === 'openrouter') return refreshKey(conn, deps, now);
   if (conn.provider === 'codex') return refreshCodex(conn, deps, store, now);
   if (conn.provider === 'gemini') return refreshQuota(conn, deps, store, now);
+  if (conn.provider === 'anthropic') return refreshOwnLogin(conn, cfg, deps, now);
   return Promise.resolve();
 }
 
@@ -97,6 +109,17 @@ async function within(ms: number, work: Promise<unknown>): Promise<void> {
 
 export async function refreshUsage(deps: ModelApiDeps, store: Store, now = Date.now()): Promise<void> {
   const cfg = store.read();
-  const work = Promise.all([...cfg.connections.map((conn) => refreshOne(conn, deps, store, now)), refreshLogin(cfg, deps, now)]);
+  const work = Promise.all([...cfg.connections.map((conn) => refreshOne(conn, cfg, deps, store, now)), refreshLogin(cfg, deps, now)]);
   await within(deps.usageWaitMs ?? WAIT_MS, work);
 }
+
+export function watchFallbackUsage(deps: ModelApiDeps = {}, every = CREDITS_TTL_MS): void {
+  const store: Store = { read: deps.read ?? readModelConfig, write: deps.write ?? writeModelConfig };
+  const run = (): void => {
+    if (!hasFallbacks(store.read())) return;
+    refreshUsage(deps, store).catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'model-api: could not refresh the usage of the fallback models');
+    });
+  };
+  setInterval(run, every).unref();
+}