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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.251",
+  "version": "0.1.0-beta.252",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.251",
+  "version": "0.1.0-beta.252",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

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

@@ -54,6 +54,7 @@ import type { StationName } from '@metro-labs/core/station-names';
 import { startUploadReaper } from '../files/upload-store.js';
 import { startAttachReaper } from '../files/attach-reaper.js';
 import { startCloudWatchPublisher } from '../server/cloudwatch.js';
+import { watchFallbackUsage } from '../gateway/usage-refresh.js';
 import { isCallEvent, leaveCallsForShutdown, onCallEvent, sweepLeftoverCalls } from '../voice/calls.js';
 
 installCrashGuard();
@@ -153,6 +154,7 @@ installBearerSessions(agentsDir(), localOwner);
   startUploadReaper();
   startAttachReaper();
   startCloudWatchPublisher();
+  watchFallbackUsage();
   announceLocalEndpoint();
   tunnel?.start();
   log.info(

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

@@ -0,0 +1,147 @@
+import { log } from '@metro-labs/core/log';
+import { lastServed } from './served.js';
+import { PER_MINUTE, usageOf, type UsageWindow } from './usage.js';
+import { bareModel, connectionOf, isSmallModel, notReady, routedConnection, routeLabel, type Connection, type Fallback, type ModelConfig, type Route } from './model-config.js';
+
+export const USAGE_LIMIT = 0.95;
+const COOLDOWN_MS = 60_000;
+const SCOPED = 'Weekly, ';
+const MS_PER_SECOND = 1000;
+
+export interface Hold {
+  reason: string;
+  until: string | null;
+}
+
+interface Cooling {
+  until: number;
+  reason: string;
+}
+
+const cooling = new Map<string, Cooling>();
+let lastChoice = '';
+
+const keyOf = (route: Route): string => `${route.connection.id}\n${route.model}`;
+
+export function forgetFallbackState(): void {
+  cooling.clear();
+  lastChoice = '';
+}
+
+function scopeOf(label: string): string | null {
+  if (!label.startsWith(SCOPED)) return null;
+  return (label.slice(SCOPED.length).trim().split(/\s+/)[0] ?? '').toLowerCase();
+}
+
+function applies(window: UsageWindow, route: Route, now: number): boolean {
+  if (window.used === null || window.label === PER_MINUTE) return false;
+  if (window.resetAt !== null && Date.parse(window.resetAt) <= now) return false;
+  if (route.connection.provider === 'gemini') return window.label === route.model;
+  const scope = scopeOf(window.label);
+  return scope === null || route.model.toLowerCase().split(/[^a-z0-9]+/).includes(scope);
+}
+
+export function windowsFor(route: Route, now = Date.now()): UsageWindow[] {
+  return (usageOf(route.connection.id)?.windows ?? []).filter((w) => applies(w, route, now));
+}
+
+const percent = (used: number): string => `${String(Math.round(used * 100))}%`;
+
+export function holdOf(route: Route, now = Date.now()): Hold | null {
+  const cool = cooling.get(keyOf(route));
+  if (cool !== undefined && cool.until > now) return { reason: cool.reason, until: new Date(cool.until).toISOString() };
+  const over = windowsFor(route, now).find((w) => (w.used ?? 0) > USAGE_LIMIT);
+  return over === undefined ? null : { reason: `${over.label} ${percent(over.used ?? 0)}`, until: over.resetAt };
+}
+
+function fallbackModel(requested: string, conn: Connection, model: string): string {
+  const bare = bareModel(requested);
+  return conn.provider === 'anthropic' && isSmallModel(bare) ? bare : model;
+}
+
+function fallbackRoute(cfg: ModelConfig, fallback: Fallback, requested: string): Route | null {
+  const conn = connectionOf(cfg, fallback.connection);
+  if (conn === null || notReady(cfg, conn) !== null) return null;
+  return { connection: conn, model: fallbackModel(requested, conn, fallback.model) };
+}
+
+const unique = (routes: Route[]): Route[] => routes.filter((route, at) => routes.findIndex((other) => keyOf(other) === keyOf(route)) === at);
+
+export const chainOf = (primary: Route, cfg: ModelConfig, requested: string): Route[] =>
+  unique([primary, ...(cfg.fallbacks ?? []).flatMap((f) => fallbackRoute(cfg, f, requested) ?? [])]);
+
+export function routesToTry(chain: Route[], now = Date.now()): Route[] {
+  const open = chain.filter((route) => holdOf(route, now) === null);
+  return open.length > 0 ? open : chain.slice(0, 1);
+}
+
+function secondsHeader(headers: Headers, name: string): number | null {
+  const raw = headers.get(name);
+  if (raw === null || raw.trim() === '') return null;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function coolUntil(headers: Headers, now: number): number {
+  const after = secondsHeader(headers, 'retry-after');
+  if (after !== null) return now + after * MS_PER_SECOND;
+  const reset = secondsHeader(headers, 'anthropic-ratelimit-unified-reset');
+  if (reset !== null && reset * MS_PER_SECOND > now) return reset * MS_PER_SECOND;
+  return now + COOLDOWN_MS;
+}
+
+export function noteRefused(route: Route, status: number, headers: Headers, next: Route | undefined, now = Date.now()): void {
+  const reason = `answered ${String(status)}`;
+  cooling.set(keyOf(route), { until: coolUntil(headers, now), reason });
+  log.warn({ from: routeLabel(route), to: next === undefined ? null : routeLabel(next), status }, 'gateway: the model hit its limit, so the request goes to the next fallback model');
+}
+
+export function noteChoice(primary: Route, chosen: Route, now = Date.now()): void {
+  const key = keyOf(chosen);
+  if (key === lastChoice) return;
+  const first = lastChoice === '';
+  lastChoice = key;
+  if (key === keyOf(primary)) {
+    if (!first) log.info({ model: routeLabel(chosen), connection: chosen.connection.label }, 'gateway: back on the first model of the fallback list');
+    return;
+  }
+  const hold = holdOf(primary, now);
+  log.info(
+    { from: routeLabel(primary), to: routeLabel(chosen), connection: chosen.connection.label, reason: hold?.reason ?? null, until: hold?.until ?? null },
+    'gateway: the first model is over its limit, so requests go to a fallback model',
+  );
+}
+
+export interface ChainRow {
+  connection: string;
+  model: string;
+  used: number | null;
+  hold: Hold | null;
+  active: boolean;
+}
+
+function primaryOf(cfg: ModelConfig): Route | null {
+  const conn = routedConnection(cfg);
+  if (conn === null) return null;
+  const served = lastServed();
+  const model = conn.model !== '' ? conn.model : served?.connection === conn.id ? served.model : '';
+  return { connection: conn, model };
+}
+
+function rowOf(cfg: ModelConfig, route: Route, now: number): Omit<ChainRow, 'active'> {
+  const reason = notReady(cfg, route.connection);
+  const used = windowsFor(route, now).reduce<number | null>((most, w) => Math.max(most ?? 0, w.used ?? 0), null);
+  return { connection: route.connection.id, model: route.model, used, hold: reason === null ? holdOf(route, now) : { reason, until: null } };
+}
+
+export function chainStatus(cfg: ModelConfig, now = Date.now()): ChainRow[] {
+  const primary = primaryOf(cfg);
+  if (primary === null) return [];
+  const listed = (cfg.fallbacks ?? []).flatMap((f) => {
+    const conn = connectionOf(cfg, f.connection);
+    return conn === null ? [] : [{ connection: conn, model: f.model }];
+  });
+  const rows = unique([primary, ...listed]).map((route) => rowOf(cfg, route, now));
+  const active = Math.max(0, rows.findIndex((row) => row.hold === null));
+  return rows.map((row, at) => ({ ...row, active: at === active }));
+}

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

@@ -1,4 +1,4 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { IncomingMessage, OutgoingHttpHeader, OutgoingHttpHeaders, ServerResponse } from 'node:http';
 import { UsageScanner } from './usage.js';
 
 export class GatewayError extends Error {
@@ -235,3 +235,41 @@ export function upstreamMessage(text: string, fallback: string): string {
     return text;
   }
 }
+
+const LIMIT_STATUSES = new Set([402, 429]);
+
+export interface Refusal {
+  status: number;
+  headers: Headers;
+}
+
+export interface Held {
+  res: ServerResponse;
+  refusal: () => Refusal | null;
+}
+
+function headersOf(raw: OutgoingHttpHeaders | OutgoingHttpHeader[] | undefined): Headers {
+  const out = new Headers();
+  if (raw === undefined || Array.isArray(raw)) return out;
+  for (const [name, value] of Object.entries(raw)) if (value !== undefined) out.set(name, Array.isArray(value) ? value.join(', ') : String(value));
+  return out;
+}
+
+export function holdLimitRefusal(res: ServerResponse): Held {
+  let refusal: Refusal | null = null;
+  const swallow = (): boolean => true;
+  const held: ServerResponse = new Proxy(res, {
+    get(target, prop) {
+      if (prop === 'writeHead')
+        return (status: number, headers?: OutgoingHttpHeaders | OutgoingHttpHeader[]): ServerResponse => {
+          if (!LIMIT_STATUSES.has(status)) return target.writeHead(status, headers);
+          refusal = { status, headers: headersOf(headers) };
+          return held;
+        };
+      if (refusal !== null && (prop === 'write' || prop === 'end')) return swallow;
+      const value: unknown = Reflect.get(target, prop, target);
+      return typeof value === 'function' ? (value as (...args: unknown[]) => unknown).bind(target) : value;
+    },
+  });
+  return { res: held, refusal: () => refusal };
+}

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

@@ -10,7 +10,8 @@ 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, parseJson, pipeResponse, readBody, sendError, upstreamMessage, watchUpstream } from './forward.js';
+import { chainOf, forgetFallbackState, noteChoice, noteRefused, routesToTry } from './fallback.js';
 import {
   BINDING_BETA,
   cappedEffort,
@@ -58,6 +59,7 @@ const learned: Adaptations = freshAdaptations();
 
 export function resetGatewayState(): void {
   forgetServed();
+  forgetFallbackState();
   forgetUsage();
   learned.fields.clear();
   learned.dropBetas = false;
@@ -237,13 +239,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 +262,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,6 +14,7 @@ import {
   parseModelConfig,
   readModelConfig,
   removeConnection,
+  setFallbacks,
   setRoute,
   updateConnection,
   writeModelConfig,
@@ -25,6 +26,7 @@ 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 +71,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 ?? '' });
@@ -133,7 +140,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 +163,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

@@ -21,10 +21,16 @@ export interface Connection {
   gemini: GeminiTokens | null;
 }
 
+export interface Fallback {
+  connection: string;
+  model: string;
+}
+
 export interface ModelConfig {
   version: 2;
   route: string;
   connections: Connection[];
+  fallbacks?: Fallback[];
 }
 
 export interface Route {
@@ -38,6 +44,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;
 
@@ -102,11 +109,29 @@ function connectionFromDisk(raw: unknown): Connection | 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 +185,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 +201,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])) {
@@ -276,7 +303,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-store.ts

@@ -5,6 +5,7 @@ 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';
 
@@ -45,6 +46,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/usage-refresh.ts

@@ -3,8 +3,8 @@ 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';
 
@@ -41,14 +41,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;
@@ -64,11 +65,11 @@ const loginIds = (cfg: ModelConfig): string[] => [
   ...cfg.connections.filter((c) => c.provider === 'anthropic' && c.apiKey === '').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 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));
@@ -76,7 +77,7 @@ async function refreshLogin(cfg: ModelConfig, deps: ModelApiDeps, now: number):
     });
   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> {
@@ -100,3 +101,14 @@ export async function refreshUsage(deps: ModelApiDeps, store: Store, now = Date.
   const work = Promise.all([...cfg.connections.map((conn) => refreshOne(conn, 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();
+}

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

@@ -3,7 +3,7 @@ import { stringOf } from '@metro-labs/http/api-http';
 
 type Key = string;
 
-interface UsageWindow {
+export interface UsageWindow {
   label: string;
   used: number | null;
   resetAt: string | null;
@@ -28,14 +28,32 @@ export interface ProviderUsage {
 export type Reported = Omit<ProviderUsage, 'tally'>;
 
 const latest = new Map<Key, Reported>();
+const stamps = new Map<Key, Map<string, number>>();
 const tallies = new Map<Key, Tally>();
 const probed = new Map<Key, number>();
 const answers = new Map<Key, Reported>();
 
 export const noteUsage = (key: Key, usage: Reported): void => {
   latest.set(key, usage);
+  stamps.set(key, new Map(usage.windows.map((w) => [w.label, Date.parse(usage.at)])));
 };
 
+export function mergeUsage(key: Key, usage: Reported): void {
+  const seen = latest.get(key);
+  const marks = stamps.get(key);
+  if (seen === undefined || marks === undefined) {
+    noteUsage(key, usage);
+    return;
+  }
+  const at = Date.parse(usage.at);
+  const newer = new Map(usage.windows.filter((w) => (marks.get(w.label) ?? Number.NEGATIVE_INFINITY) <= at).map((w) => [w.label, w]));
+  for (const label of newer.keys()) marks.set(label, at);
+  const kept = seen.windows.map((w) => newer.get(w.label) ?? w);
+  const added = [...newer.values()].filter((w) => !seen.windows.some((old) => old.label === w.label));
+  const later = Date.parse(seen.at) <= at;
+  latest.set(key, { windows: [...kept, ...added], note: later ? usage.note : seen.note, at: later ? usage.at : seen.at });
+}
+
 export function usageSeen(): Record<Key, ProviderUsage> {
   const out: Record<Key, ProviderUsage> = {};
   for (const key of new Set<Key>([...latest.keys(), ...tallies.keys()])) {
@@ -50,17 +68,20 @@ export const usageOf = (key: Key): Reported | undefined => latest.get(key);
 
 export const forgetOne = (key: Key): void => {
   latest.delete(key);
+  stamps.delete(key);
   tallies.delete(key);
   probed.delete(key);
 };
 
 export const forgetReported = (key: Key): void => {
   latest.delete(key);
+  stamps.delete(key);
   probed.delete(key);
 };
 
 export const forgetUsage = (): void => {
   latest.clear();
+  stamps.clear();
   tallies.clear();
   probed.clear();
   answers.clear();
@@ -178,13 +199,15 @@ function anthropicUnified(headers: Headers, now: Date): { windows: UsageWindow[]
   return { windows, note };
 }
 
+export const PER_MINUTE = 'Tokens per minute';
+
 function anthropicKeyed(headers: Headers, now: Date): UsageWindow[] {
   const limit = Number(headers.get('anthropic-ratelimit-tokens-limit'));
   const remaining = Number(headers.get('anthropic-ratelimit-tokens-remaining'));
   if (!Number.isFinite(limit) || !Number.isFinite(remaining) || limit <= 0) return [];
   return [
     {
-      label: 'Tokens per minute',
+      label: PER_MINUTE,
       used: clamp(1 - remaining / limit),
       resetAt: whenFrom(headers.get('anthropic-ratelimit-tokens-reset'), now),
       detail: `${remaining.toLocaleString('en-US')} of ${limit.toLocaleString('en-US')} left`,
@@ -315,7 +338,9 @@ export function claudeLoginUsage(limits: unknown, now = new Date()): Reported |
 
 export function noteUsageHeaders(kind: 'anthropic' | 'codex', key: Key, headers: Headers, now = new Date()): void {
   const usage = kind === 'anthropic' ? anthropicUsage(headers, now) : codexUsage(headers, now);
-  if (usage !== null) noteUsage(key, usage);
+  if (usage === null) return;
+  if (kind === 'anthropic') mergeUsage(key, usage);
+  else noteUsage(key, usage);
 }
 
 const dollars = (value: number): string => `$${value.toFixed(2)}`;

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.251"
+  "version": "0.1.0-beta.252"
 }