@stage-labs/metro 0.1.0-beta.21 → 0.1.0-beta.210

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

@@ -0,0 +1,208 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { refreshTokens, tokensStale, type GeminiTokens } from './gemini-auth.js';
+import { API, clientHeaders, generateBases, machineSessionId, type Bases } from './gemini-client.js';
+import { GeminiStreamTranslator } from './gemini-stream.js';
+import { toGeminiRequest } from './gemini-translate.js';
+import { ToolNames } from './codex-translate.js';
+import { GatewayError, providerStatus, sendError, upstreamMessage, type Watch } from './forward.js';
+import type { Connection } from './model-config.js';
+import { answerWhole, currentOf, errorKind, reach, refreshed, relayTranslated, sessionHeader, type TokenSource, type TokenState } from './subscription.js';
+import { effortToApply, withoutEffort } from './effort.js';
+
+export interface GeminiDeps {
+  base?: Bases;
+  tokenBase?: string;
+  fetchImpl?: typeof fetch;
+  save: (id: string, tokens: GeminiTokens) => void;
+}
+
+export type GeminiState = TokenState<GeminiTokens>;
+
+export const sharedGeminiState: GeminiState = new Map();
+
+const sourceOf = (deps: GeminiDeps): TokenSource<GeminiTokens> => ({
+  label: 'Google',
+  stale: (tokens) => tokensStale(tokens),
+  refresh: (tokens) => refreshTokens(tokens, deps.tokenBase, deps.fetchImpl),
+  save: deps.save,
+});
+
+export const currentGeminiTokens = (conn: Connection, deps: GeminiDeps, state: GeminiState): Promise<GeminiTokens> =>
+  currentOf(state, conn.id, conn.gemini, sourceOf(deps), 'Gemini is not connected: sign in with Google on the Model page.');
+
+interface Call {
+  body: Record<string, unknown>;
+  model: string;
+  promptId: string;
+  watch: Watch;
+  deps: GeminiDeps;
+  names: ToolNames;
+  conn: Connection;
+}
+
+const headersFor = (token: string, stream: boolean): Record<string, string> => ({
+  authorization: `Bearer ${token}`,
+  'content-type': 'application/json',
+  ...clientHeaders(),
+  'x-machine-session-id': machineSessionId(),
+  ...(stream ? { accept: 'text/event-stream' } : {}),
+});
+
+async function sendTo(base: string, call: Call, tokens: GeminiTokens, stream: boolean): Promise<Response> {
+  const request = toGeminiRequest(call.body, call.model, tokens.project, call.promptId, call.names);
+  const method = stream ? 'streamGenerateContent?alt=sse' : 'generateContent';
+  return (call.deps.fetchImpl ?? fetch)(`${base}/${API}:${method}`, {
+    method: 'POST',
+    headers: headersFor(tokens.accessToken, stream),
+    body: JSON.stringify(request),
+    signal: call.watch.signal,
+    redirect: 'manual',
+  });
+}
+
+async function send(call: Call, tokens: GeminiTokens, stream: boolean): Promise<Response> {
+  const bases = generateBases(call.deps.base);
+  let last: Response | null = null;
+  for (const base of bases) {
+    if (last !== null) await last.body?.cancel();
+    try {
+      last = await sendTo(base, call, tokens, stream);
+    } catch (err) {
+      if (base === bases.at(-1) || call.watch.signal.aborted) throw err;
+      continue;
+    }
+    if (last.status < 500 && last.status !== 429) return last;
+  }
+  if (last === null) throw new GatewayError(502, 'api_error', 'no Code Assist endpoint to call');
+  return last;
+}
+
+const REFUSAL_LOG_MAX = 2000;
+
+const detailText = (detail: Record<string, unknown>): string[] => {
+  const out: string[] = [];
+  if (typeof detail.reason === 'string') out.push(detail.reason);
+  if (isRecord(detail.metadata)) out.push(...Object.entries(detail.metadata).map(([k, v]) => `${k}=${String(v)}`));
+  if (typeof detail.retryDelay === 'string') out.push(`retry after ${detail.retryDelay}`);
+  if (Array.isArray(detail.violations))
+    out.push(...detail.violations.filter(isRecord).map((v) => [v.subject, v.description].filter((x) => typeof x === 'string').join(': ')));
+  return out.filter((x) => x !== '');
+};
+
+function refusalMessage(text: string, status: number): string {
+  const message = upstreamMessage(text, `Gemini answered ${String(status)}`);
+  let details: unknown = null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    details = isRecord(parsed) && isRecord(parsed.error) ? parsed.error.details : null;
+  } catch {
+    return message;
+  }
+  const notes = Array.isArray(details) ? details.filter(isRecord).flatMap(detailText) : [];
+  return notes.length === 0 ? message : `${message} (${notes.join('; ')})`;
+}
+
+const reachWith = (call: Call, state: GeminiState, stream: boolean): Promise<Response> =>
+  reach(
+    () => currentGeminiTokens(call.conn, call.deps, state),
+    (tokens) => refreshed(state, call.conn.id, tokens, sourceOf(call.deps)),
+    (tokens) => send(call, tokens, stream),
+  );
+
+export interface GeminiModel {
+  id: string;
+  name: string;
+  remaining: number | null;
+  resetAt: string | null;
+}
+
+const modelOf = (id: string, raw: unknown): GeminiModel => {
+  const entry = isRecord(raw) ? raw : {};
+  const quota = isRecord(entry.quotaInfo) ? entry.quotaInfo : null;
+  const fraction = quota !== null && typeof quota.remainingFraction === 'number' ? quota.remainingFraction : null;
+  const resetAt = quota !== null && typeof quota.resetTime === 'string' ? quota.resetTime : null;
+  return { id, name: typeof entry.displayName === 'string' ? entry.displayName : id, remaining: fraction ?? (resetAt === null ? null : 0), resetAt };
+};
+
+export async function listGeminiModels(tokens: GeminiTokens, deps: GeminiDeps): Promise<GeminiModel[]> {
+  let last = 'no Code Assist endpoint to call';
+  for (const base of generateBases(deps.base)) {
+    try {
+      const res = await (deps.fetchImpl ?? fetch)(`${base}/${API}:fetchAvailableModels`, {
+        method: 'POST',
+        headers: headersFor(tokens.accessToken, false),
+        body: JSON.stringify({ project: tokens.project }),
+        signal: AbortSignal.timeout(30_000),
+      });
+      const body: unknown = await res.json().catch(() => null);
+      if (!res.ok) {
+        last = upstreamMessage(JSON.stringify(body), `Google answered ${String(res.status)}`);
+        continue;
+      }
+      const models = isRecord(body) && isRecord(body.models) ? body.models : {};
+      return Object.entries(models)
+        .filter(([id]) => id.startsWith('gemini'))
+        .map(([id, raw]) => modelOf(id, raw));
+    } catch (err) {
+      last = errMsg(err);
+    }
+  }
+  throw new GatewayError(502, 'api_error', `could not list the Gemini models: ${last}`);
+}
+
+const parseData = (raw: string): Record<string, unknown> | null => {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+const NAMES_THINKING = /thinking|thought/i;
+
+function refuse(res: ServerResponse, model: string, status: number, text: string): void {
+  log.warn({ provider: 'gemini', model, status, body: text.slice(0, REFUSAL_LOG_MAX) }, 'gateway: the provider refused the request');
+  sendError(res, providerStatus(status), errorKind(status), refusalMessage(text, status));
+}
+
+export async function geminiMessages(
+  req: IncomingMessage,
+  res: ServerResponse,
+  body: Record<string, unknown>,
+  model: string,
+  conn: Connection,
+  deps: GeminiDeps,
+  state: GeminiState,
+  watch: Watch,
+): Promise<void> {
+  const stream = body.stream === true;
+  let call: Call = { body, model, promptId: sessionHeader(req) || 'metro', watch, deps, names: new ToolNames(), conn };
+  let upstream = await reachWith(call, state, stream);
+  if (upstream.status === 400 && effortToApply(body) !== null) {
+    const text = await upstream.text();
+    if (!NAMES_THINKING.test(text)) {
+      refuse(res, model, 400, text);
+      return;
+    }
+    log.warn({ provider: 'gemini', model }, 'gateway: Gemini refused the thinking level, so metro asked again without it');
+    call = { ...call, body: withoutEffort(body) };
+    upstream = await reachWith(call, state, stream);
+  }
+  if (!upstream.ok) {
+    refuse(res, model, upstream.status, await upstream.text());
+    return;
+  }
+  const translator = new GeminiStreamTranslator(model, (name) => call.names.restore(name));
+  if (stream) {
+    await relayTranslated(upstream, res, watch, conn.id, translator, (raw) => {
+      const data = parseData(raw.data);
+      return data === null ? '' : translator.push(data);
+    });
+    return;
+  }
+  const data = parseData(await upstream.text());
+  answerWhole(res, (data === null ? '' : translator.push(data)) + translator.close(), conn.id);
+}

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

@@ -0,0 +1,199 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { apiFailure, apiSession, cors, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+import { openrouterModels, openrouterZdrModels } from './openrouter.js';
+import { anthropicModels, bedrockModels } from './provider-models.js';
+import { routeOf, syncAvailableModelsQuietly } from '../claude/setup.js';
+import { sessionRunning, stopSession } from '../claude/session.js';
+import { forgetOne } from './usage.js';
+import {
+  addConnection,
+  parseModelConfig,
+  readModelConfig,
+  removeConnection,
+  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 { CODEX_ROUTES, codexDeviceRoute, GEMINI_ROUTES, refreshUsage } from './model-signin.js';
+
+const PATH = '/api/model';
+const CONNECTIONS = '/api/model/connections';
+const CODEX = '/api/model/codex/';
+const GEMINI = '/api/model/gemini/';
+const OPENROUTER = '/api/model/openrouter/';
+const ANTHROPIC = '/api/model/anthropic/';
+const BEDROCK = '/api/model/bedrock/';
+const BUNDLE = '/api/model/bundle';
+const RESTORE = '/api/model/restore';
+const RESTORE_MAX = 64 * 1024;
+const DEVICE_PREFIX = 'device/';
+const DEVICE_ID_RE = /^[A-Za-z0-9_-]{16,64}$/;
+
+export type { ModelApiDeps } from './model-store.js';
+
+function restartRunningSession(): boolean {
+  if (!sessionRunning()) return false;
+  stopSession();
+  return true;
+}
+
+function kept(store: Store, next: ModelConfig, deps: ModelApiDeps, note: string, fields: Record<string, unknown>): unknown {
+  const before = routeOf(store.read());
+  store.write(next);
+  syncAvailableModelsQuietly(deps.setup ?? {}, next);
+  log.info(fields, note);
+  if (routeOf(next) !== before && (deps.restartSession ?? restartRunningSession)())
+    log.info({ was: before, now: routeOf(next) }, 'model-api: the model changed, so the Claude session restarts on it');
+  return settingsBody(next);
+}
+
+async function withBody(req: IncomingMessage, run: (body: Record<string, unknown>) => ModelConfig): Promise<ModelConfig> {
+  const body = await readJsonBody(req, BODY_MAX);
+  if (!isRecord(body)) throw new ApiError('body must be a JSON object', 400);
+  try {
+    return run(body);
+  } catch (err) {
+    return asApiError(err);
+  }
+}
+
+async function chooseRoute(req: IncomingMessage, deps: ModelApiDeps, store: Store): Promise<unknown> {
+  const next = await withBody(req, (body) => setRoute(store.read(), typeof body.route === 'string' ? body.route : ''));
+  return kept(store, next, deps, 'model-api: route changed', { route: next.route });
+}
+
+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 ?? '' });
+}
+
+async function change(req: IncomingMessage, deps: ModelApiDeps, store: Store, id: string): Promise<unknown> {
+  const next = await withBody(req, (body) => updateConnection(store.read(), id, body));
+  return kept(store, next, deps, 'model-api: connection changed', { connection: id });
+}
+
+function drop(deps: ModelApiDeps, store: Store, id: string): unknown {
+  let next: ModelConfig;
+  try {
+    next = removeConnection(store.read(), id);
+  } catch (err) {
+    asApiError(err);
+  }
+  forgetOne(id);
+  return kept(store, next, deps, 'model-api: connection removed', { connection: id });
+}
+
+async function settingsWithUsage(deps: ModelApiDeps, store: Store): Promise<Record<string, unknown>> {
+  await refreshUsage(deps, store);
+  return settingsBody(store.read());
+}
+
+const OPENROUTER_ROUTES: Record<string, Route> = {
+  models: { method: 'GET', run: async (_req, deps) => ({ models: await openrouterModels(deps.openrouterBase, deps.fetchImpl).catch(asApiError) }) },
+  zdr: { method: 'GET', run: async (_req, deps) => ({ models: await openrouterZdrModels(deps.openrouterBase, deps.fetchImpl).catch(asApiError) }) },
+};
+
+const ANTHROPIC_ROUTES: Record<string, Route> = {
+  models: {
+    method: 'GET',
+    run: async (req, deps, store) => ({ models: await anthropicModels(connectionFor(store.read(), req, 'anthropic'), deps.anthropicBase, deps.fetchImpl).catch(asApiError) }),
+  },
+};
+
+const BEDROCK_ROUTES: Record<string, Route> = {
+  models: {
+    method: 'GET',
+    run: async (req, deps, store) => ({ models: await bedrockModels(connectionFor(store.read(), req, 'bedrock'), deps.bedrockControlBase, deps.fetchImpl).catch(asApiError) }),
+  },
+};
+
+const named = (table: Record<string, Route>, name: string, method: string | undefined): Route | number => {
+  const route = table[name];
+  if (route === undefined) return 404;
+  return route.method === method ? route : 405;
+};
+
+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', {});
+}
+
+function bundleRoute(path: string, method: string | undefined): Route | number {
+  if (path === BUNDLE) return method === 'GET' ? { method: 'GET', run: (_req, _deps, store) => Promise.resolve(store.read()) } : 405;
+  return method === 'POST' ? { method: 'POST', run: (req, deps, store) => restore(req, store, deps) } : 405;
+}
+
+function settingsRoute(method: string | undefined): Route | number {
+  if (method === 'GET') return { method: 'GET', run: (_req, deps, store) => settingsWithUsage(deps, store) };
+  if (method === 'PUT') return { method: 'POST', run: chooseRoute };
+  return 405;
+}
+
+function connectionsRoute(path: string, method: string | undefined): Route | number {
+  if (path === CONNECTIONS) return method === 'POST' ? { method: 'POST', run: create } : 405;
+  const id = path.slice(CONNECTIONS.length + 1);
+  if (id === '' || id.includes('/')) return 404;
+  if (method === 'PUT') return { method: 'POST', run: (req, deps, store) => change(req, deps, store, id) };
+  if (method === 'DELETE') return { method: 'GET', run: (_req, deps, store) => Promise.resolve(drop(deps, store, id)) };
+  return 405;
+}
+
+function codexRoute(rest: string, method: string | undefined): Route | number {
+  if (rest in CODEX_ROUTES) return named(CODEX_ROUTES, rest, method);
+  const id = rest.startsWith(DEVICE_PREFIX) ? rest.slice(DEVICE_PREFIX.length) : '';
+  if (!DEVICE_ID_RE.test(id)) return 404;
+  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);
+
+function routeFor(path: string, method: string | undefined): Route | number {
+  if (path === PATH) return settingsRoute(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);
+  return codexRoute(path.slice(CODEX.length), method);
+}
+
+export function handleModelRequest(req: IncomingMessage, res: ServerResponse, deps: ModelApiDeps): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (!mine(path)) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  const route = routeFor(path, req.method);
+  if (typeof route === 'number') {
+    sendJson(req, res, route, { error: route === 404 ? 'not found' : 'method not allowed' });
+    return true;
+  }
+  const store: Store = { read: deps.read ?? readModelConfig, write: deps.write ?? writeModelConfig };
+  apiSession(req)
+    .then(async (session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      sendJson(req, res, 200, await route.run(req, deps, store));
+    })
+    .catch((err: unknown) => {
+      apiFailure(req, res, err, 'model-api');
+    });
+  return true;
+}

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

@@ -0,0 +1,278 @@
+import { join } from 'node:path';
+import { 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';
+import type { CodexTokens } from './codex-auth.js';
+import { tokensFromDisk as geminiTokensFromDisk, type GeminiTokens } from './gemini-auth.js';
+
+export const PROVIDERS = ['anthropic', 'bedrock', 'openrouter', 'codex', 'gemini'] as const;
+export type Provider = (typeof PROVIDERS)[number];
+
+export interface Connection {
+  id: string;
+  provider: Provider;
+  label: string;
+  model: string;
+  apiKey: string;
+  region: string;
+  zdr: boolean;
+  codex: CodexTokens | null;
+  gemini: GeminiTokens | null;
+}
+
+export interface ModelConfig {
+  version: 2;
+  route: string;
+  connections: Connection[];
+}
+
+export interface Route {
+  connection: Connection;
+  model: string;
+}
+
+export class ModelConfigError extends Error {}
+
+const MODEL_FILE = 'model.json';
+const MAX_FIELD = 512;
+const MAX_LABEL = 60;
+const MAX_CONNECTIONS = 20;
+const PREFIX_RE = /^(anthropic|bedrock|openrouter|codex|gemini):(.+)$/;
+const SMALL_RE = /haiku/i;
+
+const LABELS: Record<Provider, string> = {
+  anthropic: 'Anthropic',
+  bedrock: 'Amazon Bedrock',
+  openrouter: 'OpenRouter',
+  codex: 'Codex (ChatGPT)',
+  gemini: 'Gemini (Google)',
+};
+
+const isProvider = (value: unknown): value is Provider => typeof value === 'string' && (PROVIDERS as readonly string[]).includes(value);
+
+const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
+const maybe = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null);
+
+export const empty = (): ModelConfig => ({ version: 2, route: '', connections: [] });
+
+const newConnection = (provider: Provider, label: string): Connection => ({
+  id: newId(),
+  provider,
+  label,
+  model: '',
+  apiKey: '',
+  region: '',
+  zdr: false,
+  codex: null,
+  gemini: null,
+});
+
+function codexFromDisk(raw: unknown): CodexTokens | null {
+  if (!isRecord(raw)) return null;
+  const accessToken = text(raw.accessToken);
+  const refreshToken = text(raw.refreshToken);
+  const accountId = text(raw.accountId);
+  if (accessToken === '' || refreshToken === '' || accountId === '') return null;
+  return {
+    accessToken,
+    refreshToken,
+    idToken: text(raw.idToken),
+    accountId,
+    email: maybe(raw.email),
+    plan: maybe(raw.plan),
+    savedAt: text(raw.savedAt) === '' ? new Date(0).toISOString() : text(raw.savedAt),
+  };
+}
+
+function connectionFromDisk(raw: unknown): Connection | null {
+  if (!isRecord(raw) || !isProvider(raw.provider)) return null;
+  const id = text(raw.id);
+  const provider = raw.provider;
+  return {
+    id: id === '' ? newId() : id,
+    provider,
+    label: text(raw.label) === '' ? LABELS[provider] : text(raw.label).slice(0, MAX_LABEL),
+    model: text(raw.model),
+    apiKey: text(raw.apiKey),
+    region: text(raw.region),
+    zdr: raw.zdr === true,
+    codex: codexFromDisk(raw.codex),
+    gemini: geminiTokensFromDisk(raw.gemini),
+  };
+}
+
+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 needsIds = (raw: unknown): boolean =>
+  isRecord(raw) && Array.isArray(raw.connections) && raw.connections.some((c: unknown) => isRecord(c) && text(c.id) === '');
+
+export function readModelConfig(dir = agentsDir()): ModelConfig {
+  const raw = readJson<unknown>(join(dir, MODEL_FILE), null, { warn: 'model-config: model.json is unreadable, so every request goes to Anthropic until it is fixed' });
+  const cfg = parseModelConfig(raw);
+  if (needsIds(raw)) writeModelConfig(cfg, dir);
+  return cfg;
+}
+
+export function writeModelConfig(cfg: ModelConfig, dir = agentsDir()): void {
+  writeSecure(join(dir, MODEL_FILE), JSON.stringify(cfg, null, 2));
+}
+
+export const connectionOf = (cfg: ModelConfig, id: string): Connection | null => cfg.connections.find((c) => c.id === id) ?? null;
+
+export const routedConnection = (cfg: ModelConfig): Connection | null => connectionOf(cfg, cfg.route);
+
+function requireConnection(cfg: ModelConfig, id: string): Connection {
+  const found = connectionOf(cfg, id);
+  if (found === null) throw new ModelConfigError('no such connection');
+  return found;
+}
+
+const PASSTHROUGH = 'Nothing is connected: the request carries the Claude Code login of the session that sent it.';
+
+const CHECKS: Record<Provider, [(c: Connection) => boolean, string][]> = {
+  anthropic: [],
+  bedrock: [
+    [(c) => c.apiKey === '', 'Bedrock needs an API key: add it on the Model page.'],
+    [(c) => c.region === '', 'Bedrock needs a region: add it on the Model page.'],
+  ],
+  openrouter: [
+    [(c) => c.apiKey === '', 'OpenRouter needs an API key: add it on the Model page.'],
+    [(c) => c.model === '', 'OpenRouter needs a model id: choose one on the Model page.'],
+  ],
+  codex: [
+    [(c) => c.codex === null, 'Codex is not connected: sign in with ChatGPT on the Model page.'],
+    [(c) => c.model === '', 'Codex needs a model id: choose one on the Model page.'],
+  ],
+  gemini: [
+    [(c) => c.gemini === null, 'Gemini is not connected: sign in with Google on the Model page.'],
+    [(c) => c.model === '', 'Gemini needs a model id: choose one on the Model page.'],
+  ],
+};
+
+export function notReady(cfg: ModelConfig, conn = routedConnection(cfg)): string | null {
+  if (conn === null) return cfg.connections.length === 0 ? null : PASSTHROUGH;
+  return CHECKS[conn.provider].find(([missing]) => missing(conn))?.[1] ?? null;
+}
+
+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),
+  bedrock: (requested, c) => (c.model === '' ? requested : c.model),
+  codex: (requested, c) => (requested.startsWith('gpt-') ? requested : c.model),
+  gemini: (requested, c) => (requested.startsWith('gemini-') ? requested : c.model),
+  anthropic: (requested, c) => (c.model === '' || isSmallModel(requested) ? requested : c.model),
+};
+
+function forProvider(cfg: ModelConfig, provider: Provider): Connection | null {
+  const routed = routedConnection(cfg);
+  if (routed?.provider === provider) return routed;
+  return cfg.connections.find((c) => c.provider === provider) ?? null;
+}
+
+export function resolveRoute(requested: string, cfg: ModelConfig): Route | null {
+  const explicit = PREFIX_RE.exec(requested);
+  if (explicit !== null && isProvider(explicit[1])) {
+    const conn = forProvider(cfg, explicit[1]);
+    return conn === null ? null : { connection: conn, model: (explicit[2] ?? '').trim() };
+  }
+  const routed = routedConnection(cfg);
+  return routed === null ? null : { connection: routed, model: DEFAULTS[routed.provider](requested, routed) };
+}
+
+export const routeLabel = (route: Route): string =>
+  route.connection.provider === 'anthropic' ? route.model : `${route.connection.provider}:${route.model}`;
+
+function publicConnection(c: Connection): Record<string, unknown> {
+  return {
+    id: c.id,
+    provider: c.provider,
+    label: c.label,
+    model: c.model,
+    hasKey: c.apiKey !== '',
+    region: c.region,
+    zdr: c.zdr,
+    signedIn: c.codex !== null || c.gemini !== null,
+    account: c.codex?.email ?? c.gemini?.email ?? null,
+    plan: c.codex?.plan ?? c.gemini?.tier ?? null,
+  };
+}
+
+export function publicModelConfig(cfg: ModelConfig): Record<string, unknown> {
+  const reason = notReady(cfg);
+  return { route: cfg.route, ready: reason === null, reason, connections: cfg.connections.map(publicConnection) };
+}
+
+const withConnection = (cfg: ModelConfig, id: string, change: (c: Connection) => Connection): ModelConfig => ({
+  ...cfg,
+  connections: cfg.connections.map((c) => (c.id === id ? change(c) : c)),
+});
+
+export const setCodexAuth = (cfg: ModelConfig, id: string, auth: CodexTokens | null): ModelConfig =>
+  withConnection(cfg, id, (c) => ({ ...c, codex: auth }));
+
+export const setGeminiAuth = (cfg: ModelConfig, id: string, auth: GeminiTokens | null): ModelConfig =>
+  withConnection(cfg, id, (c) => ({ ...c, gemini: auth }));
+
+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];
+  if (typeof value !== 'string') throw new ModelConfigError(`${what} must be a string`);
+  if (value.length > max) throw new ModelConfigError(`${what} is too long`);
+  return value.trim();
+}
+
+function flag(patch: Record<string, unknown>, key: string, current: boolean, what: string): boolean {
+  if (!(key in patch)) return current;
+  const value = patch[key];
+  if (typeof value !== 'boolean') throw new ModelConfigError(`${what} must be true or false`);
+  return value;
+}
+
+function labelFor(cfg: ModelConfig, provider: Provider, given: string): string {
+  if (given !== '') return given.slice(0, MAX_LABEL);
+  const taken = cfg.connections.filter((c) => c.provider === provider).length;
+  return taken === 0 ? LABELS[provider] : `${LABELS[provider]} ${String(taken + 1)}`;
+}
+
+export function addConnection(cfg: ModelConfig, patch: unknown): ModelConfig {
+  if (!isRecord(patch) || !isProvider(patch.provider)) throw new ModelConfigError(`provider must be one of ${PROVIDERS.join(', ')}`);
+  if (cfg.connections.length >= MAX_CONNECTIONS) throw new ModelConfigError(`a box keeps at most ${String(MAX_CONNECTIONS)} connections`);
+  const made = newConnection(patch.provider, labelFor(cfg, patch.provider, field(patch, 'label', '', 'label', MAX_LABEL)));
+  const filled = applyToConnection(made, patch);
+  return { ...cfg, route: cfg.route === '' ? filled.id : cfg.route, connections: [...cfg.connections, filled] };
+}
+
+function applyToConnection(c: Connection, patch: Record<string, unknown>): Connection {
+  return {
+    ...c,
+    label: field(patch, 'label', c.label, 'label', MAX_LABEL),
+    model: field(patch, 'model', c.model, 'model'),
+    apiKey: field(patch, 'apiKey', c.apiKey, 'API key'),
+    region: field(patch, 'region', c.region, 'region'),
+    zdr: flag(patch, 'zdr', c.zdr, 'zero data retention'),
+  };
+}
+
+export function updateConnection(cfg: ModelConfig, id: string, patch: unknown): ModelConfig {
+  if (!isRecord(patch)) throw new ModelConfigError('body must be a JSON object');
+  requireConnection(cfg, id);
+  return withConnection(cfg, id, (c) => applyToConnection(c, patch));
+}
+
+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 };
+}
+
+export function setRoute(cfg: ModelConfig, id: string): ModelConfig {
+  requireConnection(cfg, id);
+  return { ...cfg, route: id };
+}