@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.321

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

@@ -0,0 +1,118 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { stringOf } from '@metro-labs/http/api-http';
+
+type Item = Record<string, unknown>;
+
+export interface Usage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+}
+
+export const frame = (event: string, data: unknown): string => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+
+export const messageStart = (id: string, model: string): string =>
+  frame('message_start', {
+    type: 'message_start',
+    message: { id, type: 'message', role: 'assistant', model, content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 0, output_tokens: 0 } },
+  });
+
+export const messageEnd = (stop: string, usage: Usage): string =>
+  frame('message_delta', { type: 'message_delta', delta: { stop_reason: stop, stop_sequence: null }, usage }) + frame('message_stop', { type: 'message_stop' });
+
+export interface SseEvent {
+  event: string;
+  data: string;
+}
+
+export class SseParser {
+  private pending = '';
+
+  push(chunk: string): SseEvent[] {
+    this.pending += chunk;
+    const out: SseEvent[] = [];
+    for (;;) {
+      const at = this.pending.indexOf('\n\n');
+      if (at < 0) break;
+      const raw = this.pending.slice(0, at);
+      this.pending = this.pending.slice(at + 2);
+      let event = '';
+      const data: string[] = [];
+      for (const line of raw.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        else if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+      }
+      if (data.length > 0) out.push({ event, data: data.join('\n') });
+    }
+    return out;
+  }
+}
+
+export function parseEvent(raw: SseEvent): { event: string; data: Item } | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw.data);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  const event = raw.event !== '' ? raw.event : stringOf(parsed.type);
+  return event === '' ? null : { event, data: parsed };
+}
+
+interface Assembled {
+  message: Item;
+  blocks: Item[];
+}
+
+const FOLDS: Record<string, (state: Assembled, data: Item) => void> = {
+  message_start: (state, data) => {
+    if (isRecord(data.message)) state.message = { ...data.message };
+  },
+  content_block_start: (state, data) => {
+    if (isRecord(data.content_block)) state.blocks.push({ ...data.content_block });
+  },
+  content_block_delta: (state, data) => {
+    if (isRecord(data.delta)) applyDelta(state.blocks[typeof data.index === 'number' ? data.index : -1], data.delta);
+  },
+  message_delta: (state, data) => {
+    if (isRecord(data.delta)) state.message.stop_reason = data.delta.stop_reason ?? null;
+    if (isRecord(data.usage)) state.message.usage = data.usage;
+  },
+  error: (state, data) => {
+    state.message = { type: 'error', error: data.error };
+  },
+};
+
+function foldFrame(state: Assembled, event: string, data: Item): void {
+  FOLDS[event]?.(state, data);
+}
+
+function applyDelta(block: Item | undefined, delta: Item): void {
+  if (block === undefined) return;
+  if (delta.type === 'text_delta') block.text = stringOf(block.text) + stringOf(delta.text);
+  else if (delta.type === 'thinking_delta') block.thinking = stringOf(block.thinking) + stringOf(delta.thinking);
+  else if (delta.type === 'signature_delta') block.signature = stringOf(delta.signature);
+  else if (delta.type === 'input_json_delta') block.json = stringOf(block.json) + stringOf(delta.partial_json);
+}
+
+export function assembleMessage(frames: string): Item {
+  const state: Assembled = { message: {}, blocks: [] };
+  for (const raw of new SseParser().push(frames)) {
+    const parsed = parseEvent(raw);
+    if (parsed !== null) foldFrame(state, parsed.event, parsed.data);
+  }
+  if (state.message.type === 'error') return state.message;
+  const content = state.blocks.map((block) => {
+    if (block.type !== 'tool_use') return block;
+    const { json, ...rest } = block;
+    let input: unknown = {};
+    try {
+      input = JSON.parse(stringOf(json) || '{}');
+    } catch {
+      input = {};
+    }
+    return { ...rest, input };
+  });
+  return { ...state.message, content };
+}

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

@@ -0,0 +1,372 @@
+import type { 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';
+import {
+  bedrockBase,
+  bedrockCount,
+  bedrockMessages,
+  forgetAdaptations,
+  freshAdaptations,
+  type Adaptations,
+} from './bedrock.js';
+import {
+  addBeta,
+  anthropicHeaders,
+  GatewayError,
+  holdLimitRefusal,
+  SubscriptionRefused,
+  loginHeaders,
+  parseJson,
+  pipeResponse,
+  readBody,
+  sendError,
+  upstreamMessage,
+  watchUpstream,
+  type Held,
+  type Watch,
+  type Refusal,
+} from './forward.js';
+import { chainOf, forgetFallbackState, noteChoice, noteRefused, routesToTry, type Lane } from './fallback.js';
+import {
+  BINDING_BETA,
+  cappedEffort,
+  effortToApply,
+  forgetLearnedThinking,
+  helperRequest,
+  learnAlwaysThinks,
+  plannedEffort,
+  thinkingOff,
+  withBlockBinding,
+  withEffort,
+  withThinkingFor,
+} from './effort.js';
+import { helperSetup, notReady, pinnedRoute, resolveRoute, routeLabel, type Connection, type ModelSetup, type Route } from './model-config.js';
+import { codexMessages, type CodexDeps } from './codex.js';
+import { countTokens } from './subscription.js';
+import { OPENROUTER_BASE } from './openrouter.js';
+import { noteRoutewayRefusal, refusedWithPage, ROUTEWAY_BASE, routewayBody, routewayHeaders } from './routeway.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import { forgetServed, noteServed } from './served.js';
+import { forgetUsage, noteUsageHeaders, UsageScanner } from './usage.js';
+import { fitToolSearch } from './tool-search.js';
+import { siteOf } from './failures.js';
+import { orgModels } from './org-models.js';
+
+const GATEWAY_PREFIX = '/gateway';
+const MESSAGES = '/v1/messages';
+const COUNT = '/v1/messages/count_tokens';
+const MODELS = '/v1/models';
+const HELLO = '/api/hello';
+const ANTHROPIC_API = 'https://api.anthropic.com';
+const NO_ROUTE = "metro gateway: no model is set up for this agent yet: enroll it with its organization and choose a model on the organization's Models page";
+
+export interface GatewayDeps {
+  setup: () => ModelSetup;
+  identify?: (key: string) => boolean;
+  anthropicBase?: string;
+  bedrockBase?: string;
+  openrouterBase?: string;
+  routewayBase?: string;
+  codex?: Partial<CodexDeps>;
+}
+
+const learned: Adaptations = freshAdaptations();
+
+export function resetGatewayState(): void {
+  forgetServed();
+  forgetFallbackState();
+  forgetUsage();
+  forgetAdaptations(learned);
+  forgetLearnedThinking();
+}
+
+const refreshCodex = (conn: Connection): Promise<Connection | null> => orgModels()?.refresh(conn) ?? Promise.resolve(null);
+
+const keyOf = (req: IncomingMessage): string => {
+  const raw = req.headers['x-metro-key'];
+  return (Array.isArray(raw) ? raw[0] : raw)?.trim() ?? '';
+};
+
+const defaultIdentify = (key: string): boolean => key !== '' && agentIdForKey(key) !== undefined;
+
+function routesOf(setup: ModelSetup): Route[] {
+  return [...(setup.primary === null ? [] : [setup.primary]), ...setup.fallbacks].flatMap((ref) => {
+    const conn = setup.connections.find((c) => c.id === ref.connection);
+    const model = ref.model === '' ? (conn?.model ?? '') : ref.model;
+    return conn === undefined || model === '' ? [] : [{ connection: conn, model }];
+  });
+}
+
+function modelsBody(setup: ModelSetup): Record<string, unknown> {
+  const listed = routesOf(setup)
+    .filter((r) => r.connection.provider !== 'anthropic')
+    .map((r) => ({ id: routeLabel(r), display_name: `${r.connection.label} · ${r.model}`, description: 'Through metro' }));
+  const data = listed.filter((m, at) => listed.findIndex((o) => o.id === m.id) === at);
+  return { data, has_more: false, first_id: data[0]?.id ?? null, last_id: data.at(-1)?.id ?? null };
+}
+
+const noRoute = (): never => {
+  throw new GatewayError(503, 'api_error', NO_ROUTE);
+};
+
+function requestedModel(body: Record<string, unknown>): string {
+  const model = body.model;
+  if (typeof model !== 'string' || model === '') throw new GatewayError(400, 'invalid_request_error', 'model is required');
+  return model;
+}
+
+interface Payloads {
+  metro: Buffer;
+  asSent: Buffer | null;
+  bound: boolean;
+}
+
+interface Shaped {
+  raw: Buffer;
+  sent: Record<string, unknown>;
+  shaped: Record<string, unknown>;
+  bind: boolean;
+}
+
+function anthropicPayloads({ raw, sent, shaped, bind }: Shaped, model: string): Payloads {
+  const runnable = withThinkingFor(sent, model);
+  const rewrite = runnable !== sent || (typeof sent.model === 'string' && sent.model !== model);
+  const asSent = rewrite ? Buffer.from(JSON.stringify({ ...runnable, model })) : raw;
+  const fitted = withThinkingFor(shaped, model);
+  const bound = bind ? withBlockBinding(fitted) : fitted;
+  if (bound === sent) return { metro: asSent, asSent: null, bound: false };
+  return { metro: Buffer.from(JSON.stringify(rewrite ? { ...bound, model } : bound)), asSent, bound: bind && bound !== shaped };
+}
+
+type Send = (payload: Buffer, headers: Record<string, string>) => Promise<Response>;
+
+async function asAnthropicWants(send: Send, base: Record<string, string>, payloads: Payloads, connection: string, model: string): Promise<Response> {
+  const { metro, asSent, bound } = payloads;
+  const upstream = await send(metro, bound ? addBeta(base, BINDING_BETA) : base);
+  if (upstream.status !== 400 || asSent === null) return upstream;
+  const reason = upstreamMessage(await upstream.text().catch(() => ''), '').slice(0, 300);
+  log.warn({ connection, model, reason }, 'gateway: the provider refused the request metro shaped, so it was sent again as Claude Code wrote it');
+  return send(asSent, base);
+}
+
+async function refusedThinkingOff(upstream: Response, shaped: Record<string, unknown>, model: string): Promise<boolean> {
+  if (upstream.status !== 400 || !thinkingOff(shaped)) return false;
+  if (!learnAlwaysThinks(model, upstreamMessage(await upstream.clone().text(), ''))) return false;
+  await upstream.body?.cancel();
+  log.info({ model }, 'gateway: this model cannot run with thinking off, so metro leaves that setting out for it from now on');
+  return true;
+}
+
+async function refusedSubscription(conn: Connection, upstream: Response, watch: Watch): Promise<void> {
+  if (conn.apiKey !== '' || upstream.status !== 401) return;
+  await upstream.body?.cancel();
+  watch.stop();
+  throw new SubscriptionRefused(conn.label);
+}
+
+async function shapedAttempt(send: Send, base: Record<string, string>, body: Shaped, route: Route): Promise<Response> {
+  const shape = (): Promise<Response> => asAnthropicWants(send, base, anthropicPayloads(body, route.model), route.connection.label, route.model);
+  const first = await shape();
+  return (await refusedThinkingOff(first, body.shaped, route.model)) ? shape() : first;
+}
+
+const sender = (url: string, watch: Watch): Send => (payload, headers) =>
+  fetch(url, { method: 'POST', headers, body: new Uint8Array(payload), signal: watch.signal, redirect: 'manual' });
+
+const upstreamPath = (req: IncomingMessage): string => (req.url ?? '').slice(GATEWAY_PREFIX.length);
+
+async function toAnthropic(req: IncomingMessage, res: ServerResponse, body: Shaped, route: Route, deps: GatewayDeps): Promise<void> {
+  const conn = route.connection;
+  const watch = watchUpstream(res);
+  const send = sender(`${deps.anthropicBase ?? ANTHROPIC_API}${upstreamPath(req)}`, watch);
+  const upstream = await shapedAttempt(send, conn.apiKey !== '' ? anthropicHeaders(req, conn.apiKey) : loginHeaders(req, conn.claudeToken), body, route);
+  await refusedSubscription(conn, upstream, watch);
+  noteRefusal(conn.label, route.model, upstream);
+  noteUsageHeaders('anthropic', conn.id, upstream.headers);
+  await pipeResponse(upstream, res, watch, { ownCredential: true, scanner: new UsageScanner(conn.id), site: siteOf(route) });
+}
+
+async function toRouteway(req: IncomingMessage, res: ServerResponse, body: Shaped, route: Route, deps: GatewayDeps): Promise<void> {
+  const conn = route.connection;
+  const watch = watchUpstream(res);
+  const send = sender(`${deps.routewayBase ?? ROUTEWAY_BASE}${upstreamPath(req)}`, watch);
+  const sent = routewayBody(body.sent);
+  const fitted: Shaped = { raw: sent === body.sent ? body.raw : Buffer.from(JSON.stringify(sent)), sent, shaped: routewayBody(body.shaped), bind: false };
+  const upstream = await shapedAttempt(send, routewayHeaders(req, conn.apiKey), fitted, route);
+  noteRefusal(conn.label, route.model, upstream);
+  await noteRoutewayRefusal(upstream);
+  await refusedWithPage(upstream, watch);
+  await pipeResponse(upstream, res, watch, { keepalive: true, ownCredential: true, scanner: new UsageScanner(conn.id), site: siteOf(route) });
+}
+
+async function toOpenRouter(req: IncomingMessage, res: ServerResponse, body: Record<string, unknown>, route: Route, deps: GatewayDeps): Promise<void> {
+  const conn = route.connection;
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    accept: req.headers.accept ?? 'application/json',
+    authorization: `Bearer ${conn.apiKey}`,
+    'anthropic-version': typeof req.headers['anthropic-version'] === 'string' ? req.headers['anthropic-version'] : '2023-06-01',
+    'http-referer': 'https://metro.box',
+    'x-title': 'metro',
+  };
+  const beta = req.headers['anthropic-beta'];
+  if (typeof beta === 'string' && beta !== '') headers['anthropic-beta'] = beta;
+  const watch = watchUpstream(res);
+  const upstream = await fetch(`${deps.openrouterBase ?? OPENROUTER_BASE}${MESSAGES}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(openrouterBody(body, route.model, conn.zdr)),
+    signal: watch.signal,
+    redirect: 'manual',
+  });
+  noteRefusal(conn.label, route.model, upstream);
+  await pipeResponse(upstream, res, watch, { keepalive: true, ownCredential: true, scanner: new UsageScanner(conn.id), site: siteOf(route) });
+}
+
+function openrouterBody(body: Record<string, unknown>, model: string, zdr: boolean): Record<string, unknown> {
+  const sent: Record<string, unknown> = { ...body, model };
+  if (thinkingOff(body)) delete sent.thinking;
+  const effort = effortToApply(body);
+  if (effort !== null) sent.reasoning = { ...(isRecord(body.reasoning) ? body.reasoning : {}), effort: cappedEffort(effort) };
+  if (!zdr) return sent;
+  const provider = isRecord(body.provider) ? body.provider : {};
+  return { ...sent, provider: { ...provider, zdr: true } };
+}
+
+function noteRefusal(connection: string, model: string, upstream: Response): void {
+  if (!upstream.ok) log.warn({ connection, model, status: upstream.status }, 'gateway: the provider refused the request');
+}
+
+async function toCodex(req: IncomingMessage, res: ServerResponse, path: string, body: Record<string, unknown>, route: Route, deps: GatewayDeps): Promise<void> {
+  if (path === COUNT) countTokens(res, body);
+  else await codexMessages(req, res, body, route.model, route.connection, { refresh: refreshCodex, ...deps.codex }, watchUpstream(res));
+}
+
+function shapedFor(req: IncomingMessage, sent: Record<string, unknown>, setup: ModelSetup): Record<string, unknown> {
+  const effort = plannedEffort(req, sent, setup.effort);
+  return effort === null ? sent : withEffort(sent, effort);
+}
+
+interface Chosen {
+  lane: Lane;
+  setup: ModelSetup;
+  primary: Route;
+}
+
+function chosenChain(req: IncomingMessage, sent: Record<string, unknown>, setup: ModelSetup, requested: string): Chosen {
+  const helpers = helperRequest(req, sent) ? helperSetup(setup) : null;
+  if (helpers === null) return { lane: 'main', setup, primary: resolveRoute(requested, setup) ?? noRoute() };
+  return { lane: 'helpers', setup: helpers, primary: pinnedRoute(requested, helpers) ?? noRoute() };
+}
+
+const bytesOf = (raw: Buffer, parsed: Record<string, unknown>, sent: Record<string, unknown>): Buffer => (sent === parsed ? raw : Buffer.from(JSON.stringify(sent)));
+
+interface Request {
+  path: string;
+  raw: Buffer;
+  parsed: Record<string, unknown>;
+  sent: Record<string, unknown>;
+  body: Record<string, unknown>;
+  setup: ModelSetup;
+}
+
+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');
+  const reason = notReady(route);
+  if (reason !== null) throw new GatewayError(400, 'invalid_request_error', reason);
+  if (path === MESSAGES) noteServed({ connection: conn.id, provider: conn.provider, model: route.model, at: new Date().toISOString() });
+  if (conn.provider === 'bedrock') {
+    const up = { settings: conn, base: deps.bedrockBase ?? bedrockBase(conn.region), learned, watch: watchUpstream(res) };
+    if (path === COUNT) await bedrockCount(req, res, body, route.model, up);
+    else await bedrockMessages(req, res, body, route.model, up);
+    return;
+  }
+  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, deps);
+    return;
+  }
+  if (conn.provider === 'codex') {
+    await toCodex(req, res, path, body, route, deps);
+    return;
+  }
+  const shaped: Shaped = { raw: bytesOf(ask.raw, ask.parsed, ask.sent), sent: ask.sent, shaped: body, bind: true };
+  await (conn.provider === 'routeway' ? toRouteway : toAnthropic)(req, res, shaped, route, deps);
+}
+
+async function heldAttempt(req: IncomingMessage, held: Held, ask: Request, route: Route, deps: GatewayDeps): Promise<Refusal | null> {
+  try {
+    await attempt(req, held.res, ask, route, deps);
+  } catch (err) {
+    if (!(err instanceof SubscriptionRefused)) throw err;
+    return { status: 401, headers: new Headers() };
+  }
+  return held.refusal();
+}
+
+async function dispatch(req: IncomingMessage, res: ServerResponse, path: string, deps: GatewayDeps): Promise<void> {
+  const setup = deps.setup();
+  const raw = await readBody(req);
+  const parsed = parseJson(raw);
+  const sent = fitToolSearch(req, parsed);
+  const requested = requestedModel(sent);
+  const { lane, setup: chain, primary } = chosenChain(req, sent, setup, requested);
+  const ask: Request = { path, raw, parsed, sent, body: shapedFor(req, sent, setup), setup };
+  const routes = routesToTry(chainOf(primary, chain, requested));
+  for (const [at, route] of routes.entries()) {
+    const next = routes[at + 1];
+    if (path === MESSAGES) noteChoice(primary, route, lane);
+    if (next === undefined) {
+      await attempt(req, res, ask, route, deps);
+      return;
+    }
+    const refusal = await heldAttempt(req, holdLimitRefusal(res), ask, route, deps);
+    if (refusal === null) return;
+    noteRefused(route, refusal.status, refusal.headers, next);
+  }
+}
+
+function failed(res: ServerResponse, err: unknown): void {
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  if (err instanceof GatewayError) {
+    sendError(res, err.status, err.kind, err.message);
+    return;
+  }
+  log.warn({ err: errMsg(err) }, 'gateway: request failed');
+  sendError(res, 502, 'api_error', `metro gateway: ${errMsg(err)}`);
+}
+
+function answer(req: IncomingMessage, res: ServerResponse, path: string, deps: GatewayDeps): void {
+  if (req.method === 'GET' && path === MODELS) {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(modelsBody(deps.setup())));
+    return;
+  }
+  if (req.method === 'POST' && (path === MESSAGES || path === COUNT)) {
+    dispatch(req, res, path, deps).catch((err: unknown) => {
+      failed(res, err);
+    });
+    return;
+  }
+  sendError(res, 404, 'not_found_error', 'not found');
+}
+
+export function handleGatewayRequest(req: IncomingMessage, res: ServerResponse, deps: GatewayDeps): boolean {
+  const full = req.url ?? '';
+  if (full !== GATEWAY_PREFIX && !full.startsWith(`${GATEWAY_PREFIX}/`)) return false;
+  const path = (full.split('?')[0] ?? '').slice(GATEWAY_PREFIX.length);
+  if (req.method === 'HEAD' && path === HELLO) {
+    res.writeHead(200).end();
+    return true;
+  }
+  if (cameThroughProxy(req)) sendError(res, 401, 'authentication_error', 'metro gateway: the agent key works only on this machine, not through its public address');
+  else if ((deps.identify ?? defaultIdentify)(keyOf(req))) answer(req, res, path, deps);
+  else sendError(res, 401, 'authentication_error', 'metro gateway: no agent key (x-metro-key); start the agent with metro agent');
+  return true;
+}

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

@@ -0,0 +1,121 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { EFFORT_DEFAULTS } from '@metro-labs/core/effort';
+import { ApiError } from '@metro-labs/http/api-error';
+import { apiFailure, apiSession, cors, sendJson } from '@metro-labs/http/api-http';
+import { effectiveSetup } from './effective.js';
+import { chainStatus } from './fallback.js';
+import { helperSetup, notReady, primaryRoute, type Connection, type ModelSetup } from './model-config.js';
+import { orgModels, type SyncStatus } from './org-models.js';
+import { lastServed } from './served.js';
+import { refreshUsage, type UsageDeps } from './usage-refresh.js';
+import { usageSeen } from './usage.js';
+
+const PATH = '/api/model';
+const SNAPSHOT = '/api/model/snapshot';
+const SYNC = '/api/model/sync';
+
+export interface ModelApiDeps extends UsageDeps {
+  setup?: () => ModelSetup;
+  sync?: () => Promise<void>;
+  syncStatus?: () => SyncStatus;
+}
+
+const NO_SYNC: SyncStatus = { enrolled: false, at: null, error: null };
+const NO_MODEL = "No model is set up for this agent yet: choose one on the organization's Models page.";
+
+function publicConnection(c: Connection): Record<string, unknown> {
+  return {
+    id: c.id,
+    provider: c.provider,
+    label: c.label,
+    model: c.model,
+    hasKey: c.apiKey !== '',
+    subscription: c.claudeToken !== '',
+    region: c.region,
+    zdr: c.zdr,
+    signedOut: c.signedOut,
+    account: c.account.email,
+    plan: c.account.plan,
+    method: c.account.method,
+  };
+}
+
+const setupOf = (deps: ModelApiDeps): ModelSetup => (deps.setup ?? (() => effectiveSetup()))();
+
+function helpersBody(setup: ModelSetup): Record<string, unknown> | null {
+  const helpers = helperSetup(setup);
+  if (helpers === null) return null;
+  const primary = primaryRoute(helpers);
+  return { route: primary?.connection.id ?? '', model: primary?.model ?? '', fallbacks: helpers.fallbacks, chain: chainStatus(helpers) };
+}
+
+export function settingsBody(deps: ModelApiDeps): Record<string, unknown> {
+  const setup = setupOf(deps);
+  const primary = primaryRoute(setup);
+  const reason = primary === null ? NO_MODEL : notReady(primary);
+  return {
+    source: setup.source,
+    sync: (deps.syncStatus ?? (() => orgModels()?.syncStatus() ?? NO_SYNC))(),
+    route: primary?.connection.id ?? '',
+    model: primary?.model ?? '',
+    ready: reason === null,
+    reason,
+    connections: setup.connections.map(publicConnection),
+    fallbacks: setup.fallbacks,
+    chain: chainStatus(setup),
+    helpers: helpersBody(setup),
+    effort: { ...EFFORT_DEFAULTS, ...setup.effort },
+    lastServed: lastServed(),
+    usage: usageSeen(),
+  };
+}
+
+async function withUsage(deps: ModelApiDeps): Promise<Record<string, unknown>> {
+  await refreshUsage(setupOf(deps), deps);
+  return settingsBody(deps);
+}
+
+async function synced(deps: ModelApiDeps): Promise<Record<string, unknown>> {
+  await (deps.sync ?? (() => orgModels()?.requested() ?? Promise.resolve()))();
+  return settingsBody(deps);
+}
+
+type Run = () => Promise<unknown>;
+
+const ROUTES: Record<string, [string, (deps: ModelApiDeps) => Promise<unknown>]> = {
+  [PATH]: ['GET', withUsage],
+  [SNAPSHOT]: ['GET', (deps) => Promise.resolve(settingsBody(deps))],
+  [SYNC]: ['POST', synced],
+};
+
+function routeFor(path: string, method: string | undefined, deps: ModelApiDeps): Run | number {
+  const known = ROUTES[path];
+  if (known === undefined) return 404;
+  const [wanted, run] = known;
+  return method === wanted ? () => run(deps) : 405;
+}
+
+const mine = (path: string): boolean => path === PATH || path.startsWith(`${PATH}/`);
+
+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, deps);
+  if (typeof route === 'number') {
+    sendJson(req, res, route, { error: route === 404 ? 'not found' : 'method not allowed' });
+    return true;
+  }
+  apiSession(req)
+    .then(async (session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      sendJson(req, res, 200, await route());
+    })
+    .catch((err: unknown) => {
+      apiFailure(req, res, err, 'model-api');
+    });
+  return true;
+}