@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -0,0 +1,159 @@
+export const PROVIDERS = ['anthropic', 'bedrock', 'openrouter', 'codex'] as const;
+export type Provider = (typeof PROVIDERS)[number];
+export type CodexMethod = 'chatgpt' | 'code';
+export type RouteSource = 'agent' | 'organization';
+
+export interface CodexAccess {
+  method: CodexMethod;
+  accessToken: string;
+  expiresAt: number;
+  accountId: string | null;
+}
+
+export interface Account {
+  email: string | null;
+  plan: string | null;
+  method: CodexMethod | null;
+}
+
+export interface Connection {
+  id: string;
+  provider: Provider;
+  label: string;
+  model: string;
+  apiKey: string;
+  region: string;
+  zdr: boolean;
+  revision: number;
+  codex: CodexAccess | null;
+  claude: string | null;
+  account: Account;
+  signedOut: boolean;
+}
+
+export interface Fallback {
+  connection: string;
+  model: string;
+}
+
+export interface ModelSetup {
+  primary: Fallback | null;
+  fallbacks: Fallback[];
+  connections: Connection[];
+  source: RouteSource | null;
+}
+
+export interface Route {
+  connection: Connection;
+  model: string;
+}
+
+export const LOCAL_PREFIX = 'local:';
+export const SESSION_LOGIN = `${LOCAL_PREFIX}session`;
+export const CODEX_SIGN_IN = "Codex is not signed in: sign in again on the organization's Models page.";
+
+const PREFIX_RE = /^(anthropic|bedrock|openrouter|codex):(.+)$/;
+const SMALL_RE = /haiku/i;
+const NO_ACCOUNT: Account = { email: null, plan: null, method: null };
+
+export const isProvider = (value: unknown): value is Provider => typeof value === 'string' && (PROVIDERS as readonly string[]).includes(value);
+
+export const emptySetup = (): ModelSetup => ({ primary: null, fallbacks: [], connections: [], source: null });
+
+export const loginRef = (login: string): string => `${LOCAL_PREFIX}${login}`;
+
+const localConnection = (id: string, label: string, claude: string | null, account: Account, missing: boolean): Connection => ({
+  id,
+  provider: 'anthropic',
+  label,
+  model: '',
+  apiKey: '',
+  region: '',
+  zdr: false,
+  revision: 0,
+  codex: null,
+  claude,
+  account,
+  signedOut: missing,
+});
+
+export const sessionConnection = (): Connection => localConnection(SESSION_LOGIN, 'Claude Code login', null, NO_ACCOUNT, false);
+
+export interface LocalLogin {
+  id: string;
+  email: string | null;
+  plan: string | null;
+}
+
+export function loginConnection(login: string, known: LocalLogin | undefined): Connection {
+  const account = known === undefined ? NO_ACCOUNT : { email: known.email, plan: known.plan, method: null };
+  return localConnection(loginRef(login), known?.email ?? 'Claude login', login, account, known === undefined);
+}
+
+export const connectionOf = (setup: ModelSetup, id: string): Connection | null => setup.connections.find((c) => c.id === id) ?? null;
+
+export function primaryRoute(setup: ModelSetup): Route | null {
+  const primary = setup.primary;
+  const conn = primary === null ? null : connectionOf(setup, primary.connection);
+  if (primary === null || conn === null) return null;
+  return { connection: conn, model: primary.model === '' ? conn.model : primary.model };
+}
+
+const MISSING_LOGIN = 'This Claude login is not on this box: sign in again on the Model page.';
+
+const CHECKS: Record<Provider, [(r: Route) => boolean, string][]> = {
+  anthropic: [
+    [(r) => r.connection.claude !== null && r.connection.signedOut, MISSING_LOGIN],
+    [(r) => !r.connection.id.startsWith(LOCAL_PREFIX) && r.connection.apiKey === '', "Anthropic has no API key: add it on the organization's Models page."],
+  ],
+  bedrock: [
+    [(r) => r.connection.apiKey === '', "Bedrock has no API key: add it on the organization's Models page."],
+    [(r) => r.connection.region === '', "Bedrock needs a region: add it on the organization's Models page."],
+  ],
+  openrouter: [
+    [(r) => r.connection.apiKey === '', "OpenRouter has no API key: add it on the organization's Models page."],
+    [(r) => r.model === '', "OpenRouter needs a model id: choose one on the organization's Models page."],
+  ],
+  codex: [
+    [(r) => r.connection.codex === null, CODEX_SIGN_IN],
+    [(r) => r.model === '', "Codex needs a model id: choose one on the organization's Models page."],
+  ],
+};
+
+export const notReady = (route: Route): string | null => CHECKS[route.connection.provider].find(([missing]) => missing(route))?.[1] ?? null;
+
+export const isSmallModel = (requested: string): boolean => SMALL_RE.test(requested);
+
+const DEFAULTS: Record<Provider, (requested: string, model: string) => string> = {
+  openrouter: (requested, model) => (requested.includes('/') ? requested : model),
+  bedrock: (requested, model) => (model === '' ? requested : model),
+  codex: (requested, model) => (requested.startsWith('gpt-') ? requested : model),
+  anthropic: (requested, model) => (model === '' || isSmallModel(requested) ? requested : model),
+};
+
+function forProvider(setup: ModelSetup, provider: Provider): Connection | null {
+  const routed = primaryRoute(setup)?.connection ?? null;
+  if (routed?.provider === provider) return routed;
+  return setup.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, setup: ModelSetup): Route | null {
+  const explicit = PREFIX_RE.exec(requested);
+  if (explicit !== null && isProvider(explicit[1])) {
+    const conn = forProvider(setup, explicit[1]);
+    if (conn !== null) return { connection: conn, model: (explicit[2] ?? '').trim() };
+  }
+  const primary = primaryRoute(setup);
+  if (primary === null) return null;
+  return { connection: primary.connection, model: DEFAULTS[primary.connection.provider](bareModel(requested), primary.model) };
+}
+
+export const routeLabel = (route: Route): string =>
+  route.connection.provider === 'anthropic' ? route.model : `${route.connection.provider}:${route.model}`;
+
+export function runnerModel(setup: ModelSetup): string | null {
+  const primary = primaryRoute(setup);
+  return primary === null || primary.model === '' ? null : routeLabel(primary);
+}

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

@@ -0,0 +1,42 @@
+import { lstatSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { agentsDir } from '../agents/files.js';
+
+const LEFTOVER_RE = /^chatgpt-host\.json(?:\.tmp-[0-9]+)?$/;
+
+const codeOf = (err: unknown): unknown => (err instanceof Error && 'code' in err ? err.code : undefined);
+
+function namesIn(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((name) => LEFTOVER_RE.test(name));
+  } catch (err) {
+    if (codeOf(err) !== 'ENOENT') log.warn({ err: errMsg(err), dir }, 'org-models: could not list the old model files');
+    return [];
+  }
+}
+
+function removeOne(path: string): boolean {
+  try {
+    if (!lstatSync(path).isFile()) {
+      log.warn({ path }, 'org-models: left an old model file alone, it is not a regular file');
+      return false;
+    }
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    if (codeOf(err) !== 'ENOENT') log.warn({ err: errMsg(err), path }, 'org-models: could not remove an old model file');
+    return false;
+  }
+}
+
+export function removeModelLeftovers(dir = agentsDir()): number {
+  try {
+    const removed = namesIn(dir).filter((name) => removeOne(join(dir, name))).length;
+    log.info({ removed }, 'org-models: removed the files of the old model setup');
+    return removed;
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'org-models: could not remove the files of the old model setup');
+    return 0;
+  }
+}

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

@@ -0,0 +1,40 @@
+import { errMsg, log } from '@metro-labs/core/log';
+
+export const LIST_TTL_MS = 60 * 60_000;
+export const RETRY_MS = 5 * 60_000;
+
+export interface ListCache<T> {
+  peek: (key: string) => T[] | null;
+  refresh: (key: string, load: () => Promise<T[]>) => Promise<void>;
+}
+
+const clears = new Set<() => void>();
+
+export function listCache<T>(name: string, now: () => number = Date.now): ListCache<T> {
+  const kept = new Map<string, { at: number; list: T[] }>();
+  const tried = new Map<string, number>();
+  clears.add(() => {
+    kept.clear();
+    tried.clear();
+  });
+  const fresh = (key: string): boolean => {
+    const hit = kept.get(key);
+    return hit !== undefined && now() - hit.at < LIST_TTL_MS;
+  };
+  return {
+    peek: (key) => kept.get(key)?.list ?? null,
+    async refresh(key, load) {
+      if (fresh(key) || now() - (tried.get(key) ?? Number.NEGATIVE_INFINITY) < RETRY_MS) return;
+      tried.set(key, now());
+      try {
+        kept.set(key, { at: now(), list: await load() });
+      } catch (err) {
+        log.warn({ list: name, err: errMsg(err) }, 'model-lists: the provider would not list its models, so the last list it gave stands');
+      }
+    },
+  };
+}
+
+export function forgetModelLists(): void {
+  for (const clear of clears) clear();
+}

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

@@ -0,0 +1,25 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { GatewayError } from './forward.js';
+import type { KeySpend } from './usage.js';
+
+export const OPENROUTER_BASE = 'https://openrouter.ai/api';
+const KEY_TIMEOUT_MS = 10_000;
+
+const nullableAmount = (raw: unknown): number | null => (typeof raw === 'number' && Number.isFinite(raw) ? raw : null);
+
+export async function openrouterKey(apiKey: string, base = OPENROUTER_BASE, fetchImpl: typeof fetch = fetch): Promise<KeySpend> {
+  const res = await fetchImpl(`${base}/v1/key`, {
+    headers: { accept: 'application/json', authorization: `Bearer ${apiKey}` },
+    redirect: 'manual',
+    signal: AbortSignal.timeout(KEY_TIMEOUT_MS),
+  });
+  if (!res.ok) {
+    await res.body?.cancel();
+    throw new GatewayError(res.status, 'api_error', `OpenRouter would not describe the stored key (${String(res.status)})`);
+  }
+  const body: unknown = await res.json();
+  const data = isRecord(body) && isRecord(body.data) ? body.data : {};
+  const spent = nullableAmount(data.usage);
+  if (spent === null) throw new GatewayError(502, 'api_error', 'OpenRouter answered with no spend for the key');
+  return { limit: nullableAmount(data.limit), remaining: nullableAmount(data.limit_remaining), spent };
+}

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

@@ -0,0 +1,203 @@
+import { errMsg, log } from '@metro-labs/core/log';
+import type { AgentKey } from '../connectors/agent-key.js';
+import { agentCall, MetroApiRefusal, type MetroApi } from '../connectors/metro-api.js';
+import { deliveredOf, refreshedConnection, type Delivered } from './delivered.js';
+import type { Connection } from './model-config.js';
+
+const MODELS_PATH = '/api/agents/models';
+const REFRESH_PATH = '/api/agents/models/refresh';
+const SYNC_MS = 60_000;
+const PAGE_SYNC_MS = 5_000;
+const AGENT_KEY_MISSING = 'agent_key_missing';
+
+export interface OrgModelsDeps {
+  owner: () => string | null;
+  key: () => AgentKey | null;
+  api: MetroApi;
+  pageSyncMs?: number;
+}
+
+export interface SyncStatus {
+  enrolled: boolean;
+  at: string | null;
+  error: string | null;
+}
+
+const identityRefused = (err: unknown): boolean => err instanceof MetroApiRefusal && err.upstreamStatus === 401 && err.code === AGENT_KEY_MISSING;
+
+export class OrgModels {
+  private kept: Delivered | null = null;
+  private status: SyncStatus = { enrolled: false, at: null, error: null };
+  private running: Promise<void> | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private trailing: ReturnType<typeof setTimeout> | null = null;
+  private pageAt = Number.NEGATIVE_INFINITY;
+  private readonly refreshing = new Map<string, Promise<Connection | null>>();
+  private readonly listeners = new Set<() => void>();
+
+  constructor(private readonly deps: OrgModelsDeps) {}
+
+  current(): Delivered | null {
+    return this.kept;
+  }
+
+  syncStatus(): SyncStatus {
+    return { ...this.status };
+  }
+
+  onChange(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  sync(): Promise<void> {
+    this.running ??= this.run().finally(() => {
+      this.running = null;
+    });
+    return this.running;
+  }
+
+  requested(): Promise<void> {
+    const now = this.deps.api.now();
+    const wait = this.pageAt + (this.deps.pageSyncMs ?? PAGE_SYNC_MS) - now;
+    if (wait <= 0) {
+      this.pageAt = now;
+      return this.sync();
+    }
+    this.trailing ??= this.later(wait);
+    return this.running ?? Promise.resolve();
+  }
+
+  start(everyMs = SYNC_MS): void {
+    if (this.timer !== null) return;
+    const tick = (): void => {
+      this.sync().catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'org-models: the model setup could not be read');
+      });
+    };
+    tick();
+    this.timer = setInterval(tick, everyMs);
+    this.timer.unref();
+  }
+
+  stop(): void {
+    if (this.timer !== null) clearInterval(this.timer);
+    if (this.trailing !== null) clearTimeout(this.trailing);
+    this.timer = null;
+    this.trailing = null;
+  }
+
+  refresh(conn: Connection): Promise<Connection | null> {
+    const newer = this.kept?.connections.find((c) => c.id === conn.id && c.revision > conn.revision);
+    if (newer !== undefined) return Promise.resolve(newer);
+    const slot = `${conn.id}\n${String(conn.revision)}`;
+    const found = this.refreshing.get(slot);
+    if (found !== undefined) return found;
+    const run = this.askRefresh(conn).finally(() => {
+      this.refreshing.delete(slot);
+    });
+    this.refreshing.set(slot, run);
+    return run;
+  }
+
+  private later(wait: number): ReturnType<typeof setTimeout> {
+    const timer = setTimeout(() => {
+      this.trailing = null;
+      this.requested().catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'org-models: the model setup could not be read');
+      });
+    }, wait);
+    timer.unref();
+    return timer;
+  }
+
+  private enrolledKey(): AgentKey | null {
+    try {
+      const key = this.deps.key();
+      const owner = this.deps.owner();
+      return key !== null && owner !== null && key.enrollment?.organization === owner ? key : null;
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'org-models: the agent key could not be read');
+      return null;
+    }
+  }
+
+  private keep(next: Delivered | null): void {
+    const changed = JSON.stringify(next) !== JSON.stringify(this.kept);
+    this.kept = next;
+    if (changed) this.notify();
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners])
+      try {
+        listener();
+      } catch (err) {
+        log.warn({ err: errMsg(err) }, 'org-models: a model change listener failed');
+      }
+  }
+
+  private failed(error: string, clear: boolean): void {
+    if (this.status.error !== error) log.warn({ err: error, kept: !clear && this.kept !== null }, clear ? 'org-models: api.metro.box no longer knows this agent key, so the model setup is cleared' : 'org-models: api.metro.box did not deliver the model setup, so the last one stands');
+    this.status = { ...this.status, error };
+    if (clear) this.keep(null);
+  }
+
+  private async run(): Promise<void> {
+    const key = this.enrolledKey();
+    if (key === null) {
+      this.status = { enrolled: false, at: null, error: null };
+      this.keep(null);
+      return;
+    }
+    this.status = { ...this.status, enrolled: true };
+    try {
+      const delivered = deliveredOf(await agentCall(this.deps.api, key, MODELS_PATH, {}));
+      if (delivered === null) {
+        this.failed('api.metro.box sent a model setup Metro cannot read', false);
+        return;
+      }
+      if (this.status.error !== null) log.info('org-models: the model setup is read from api.metro.box again');
+      this.status = { enrolled: true, at: new Date(this.deps.api.now()).toISOString(), error: null };
+      this.keep(delivered);
+    } catch (err) {
+      this.failed(errMsg(err), identityRefused(err));
+    }
+  }
+
+  private async askRefresh(conn: Connection): Promise<Connection | null> {
+    const key = this.enrolledKey();
+    if (key === null) return null;
+    try {
+      const fresh = refreshedConnection(await agentCall(this.deps.api, key, REFRESH_PATH, { connection: conn.id, revision: conn.revision }));
+      if (fresh?.id !== conn.id) throw new Error('api.metro.box answered the refresh with another connection');
+      const kept = this.kept;
+      if (kept !== null) this.keep({ ...kept, connections: kept.connections.map((c) => (c.id === fresh.id ? fresh : c)) });
+      log.info({ connection: conn.id, revision: fresh.revision }, 'org-models: api.metro.box renewed the sign-in of a connection');
+      return fresh;
+    } catch (err) {
+      log.warn({ connection: conn.id, err: errMsg(err) }, 'org-models: api.metro.box could not renew the sign-in of a connection');
+      return null;
+    }
+  }
+}
+
+let shared: OrgModels | null = null;
+
+export const orgModels = (): OrgModels | null => shared;
+
+export const deliveredSetup = (): Delivered | null => shared?.current() ?? null;
+
+export function startOrgModels(deps: OrgModelsDeps, everyMs = SYNC_MS): OrgModels {
+  shared?.stop();
+  shared = new OrgModels(deps);
+  shared.start(everyMs);
+  log.info('org-models: the model setup comes from the organization on api.metro.box once the agent is enrolled');
+  return shared;
+}
+
+export function stopOrgModels(): void {
+  shared?.stop();
+}

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

@@ -0,0 +1,77 @@
+import type { IncomingHttpHeaders } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { GatewayError, OAUTH_BETA } from './forward.js';
+import { listCache } from './model-lists.js';
+import { stringOf } from '@metro-labs/http/api-http';
+
+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 BEARER = 'Bearer ';
+
+export interface ProviderModel {
+  id: string;
+  name: string;
+}
+
+interface Dated extends ProviderModel {
+  created: string;
+}
+
+const KNOWN_CLAUDE: ProviderModel[] = [
+  { id: 'claude-sonnet-5-5', name: 'Claude Sonnet 5.5' },
+  { id: 'claude-opus-5-5', name: 'Claude Opus 5.5' },
+  { id: 'claude-fable-5-1', name: 'Claude Fable 5.1' },
+  { id: 'claude-opus-5', name: 'Claude Opus 5' },
+  { id: 'claude-sonnet-5', name: 'Claude Sonnet 5' },
+  { id: 'claude-haiku-4-5', name: 'Claude Haiku 4.5' },
+];
+
+const claudeLists = listCache<ProviderModel>('anthropic');
+
+const newestFirst = (list: Dated[]): ProviderModel[] =>
+  list.sort((a, b) => b.created.localeCompare(a.created) || a.id.localeCompare(b.id)).map(({ id, name }) => ({ id, name }));
+
+function claudeEntry(entry: unknown): Dated[] {
+  if (!isRecord(entry) || stringOf(entry.id) === '') return [];
+  const type = stringOf(entry.type);
+  if (type !== '' && type !== 'model') return [];
+  const id = stringOf(entry.id);
+  return [{ id, name: stringOf(entry.display_name) || id, created: stringOf(entry.created_at) }];
+}
+
+async function listClaude(auth: Record<string, string>, what: string, base: string, fetchImpl: typeof fetch): Promise<ProviderModel[]> {
+  const res = await fetchImpl(`${base}/v1/models?limit=${String(LIST_MAX)}`, {
+    headers: { ...auth, 'anthropic-version': ANTHROPIC_VERSION, accept: 'application/json' },
+    redirect: 'manual',
+    signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new GatewayError(res.status, 'api_error', `Anthropic would not list its models with ${what} (${String(res.status)})`);
+  const body: unknown = await res.json();
+  const data = isRecord(body) && Array.isArray(body.data) ? body.data : null;
+  if (data === null) throw new GatewayError(502, 'api_error', 'Anthropic answered with no model list');
+  return newestFirst(data.flatMap(claudeEntry));
+}
+
+const loginKey = (base: string): string => `login:${base}`;
+
+const first = (value: string | string[] | undefined): string => (Array.isArray(value) ? value[0] : value)?.trim() ?? '';
+
+function loginAuth(headers: IncomingHttpHeaders): Record<string, string> | null {
+  const bearer = first(headers.authorization);
+  if (bearer.startsWith(BEARER) && bearer.length > BEARER.length) return { authorization: bearer, 'anthropic-beta': OAUTH_BETA };
+  const key = first(headers['x-api-key']);
+  return key === '' ? null : { 'x-api-key': key };
+}
+
+export function refreshLoginModels(headers: IncomingHttpHeaders, base = ANTHROPIC_API, fetchImpl: typeof fetch = fetch): Promise<void> {
+  const auth = loginAuth(headers);
+  if (auth === null) return Promise.resolve();
+  return claudeLists.refresh(loginKey(base), () => listClaude(auth, 'the Claude Code login', base, fetchImpl));
+}
+
+export function claudeModels(base = ANTHROPIC_API): ProviderModel[] {
+  const live = claudeLists.peek(loginKey(base)) ?? [];
+  return live.length > 0 ? live : KNOWN_CLAUDE;
+}

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

@@ -0,0 +1,18 @@
+export interface Served {
+  connection: string;
+  provider: string;
+  model: string;
+  at: string;
+}
+
+let last: Served | null = null;
+
+export const noteServed = (served: Served): void => {
+  last = served;
+};
+
+export const lastServed = (): Served | null => last;
+
+export const forgetServed = (): void => {
+  last = null;
+};

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

@@ -0,0 +1,120 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { assembleMessage, SseParser, type SseEvent } from './frames.js';
+import { GatewayError, relayFrames, type Watch } from './forward.js';
+import { UsageScanner } from './usage.js';
+
+const STATUS_OF: Record<string, number> = { rate_limit_error: 429, invalid_request_error: 400, permission_error: 403, overloaded_error: 529 };
+
+interface Slot<T> {
+  refreshing: Promise<T> | null;
+  latest: T | null;
+}
+
+export type TokenState<T> = Map<string, Slot<T>>;
+
+export interface TokenSource<T extends { savedAt: string }> {
+  label: string;
+  stale: (tokens: T) => boolean;
+  refresh: (tokens: T) => Promise<T>;
+  save: (id: string, tokens: T) => void;
+}
+
+function slotFor<T>(state: TokenState<T>, id: string): Slot<T> {
+  const found = state.get(id);
+  if (found !== undefined) return found;
+  const made: Slot<T> = { refreshing: null, latest: null };
+  state.set(id, made);
+  return made;
+}
+
+const newerThan = (a: { savedAt: string }, b: { savedAt: string }): boolean => Date.parse(a.savedAt) > Date.parse(b.savedAt);
+
+export function refreshed<T extends { savedAt: string }>(state: TokenState<T>, id: string, tokens: T, source: TokenSource<T>): Promise<T> {
+  const slot = slotFor(state, id);
+  const latest = slot.latest;
+  if (latest !== null && newerThan(latest, tokens) && !source.stale(latest)) return Promise.resolve(latest);
+  if (slot.refreshing !== null) return slot.refreshing;
+  const run = source
+    .refresh(tokens)
+    .then((fresh) => {
+      source.save(id, fresh);
+      slot.latest = fresh;
+      return fresh;
+    })
+    .catch((err: unknown) => {
+      throw new GatewayError(403, 'permission_error', `${source.label} sign-in expired (${errMsg(err)}): connect again on the Model page`);
+    })
+    .finally(() => {
+      slot.refreshing = null;
+    });
+  slot.refreshing = run;
+  return run;
+}
+
+export function currentOf<T extends { savedAt: string }>(state: TokenState<T>, id: string, tokens: T | null, source: TokenSource<T>, missing: string): Promise<T> {
+  if (tokens === null) throw new GatewayError(400, 'invalid_request_error', missing);
+  return source.stale(tokens) ? refreshed(state, id, tokens, source) : Promise.resolve(tokens);
+}
+
+export async function reach<T>(current: () => Promise<T>, again: (tokens: T) => Promise<T>, send: (tokens: T) => Promise<Response>): Promise<Response> {
+  const tokens = await current();
+  const upstream = await send(tokens);
+  if (upstream.status !== 401) return upstream;
+  await upstream.body?.cancel();
+  return send(await again(tokens));
+}
+
+export function errorKind(status: number, invalid: readonly number[] = [400, 404]): string {
+  if (status === 401 || status === 403) return 'permission_error';
+  if (status === 429) return 'rate_limit_error';
+  if (invalid.includes(status)) return 'invalid_request_error';
+  return 'api_error';
+}
+
+export function sessionHeader(req: IncomingMessage): string {
+  const raw = req.headers['x-claude-code-session-id'];
+  return (Array.isArray(raw) ? raw[0] : raw)?.trim() ?? '';
+}
+
+interface Translator {
+  readonly finished: boolean;
+  close: (message?: string) => string;
+}
+
+export function relayTranslated(
+  upstream: Response,
+  res: ServerResponse,
+  watch: Watch,
+  key: string,
+  translator: Translator,
+  onEvent: (raw: SseEvent) => string,
+): Promise<void> {
+  const parser = new SseParser();
+  const decoder = new TextDecoder();
+  return relayFrames(upstream, res, watch, key, {
+    push: (chunk, emit) => {
+      for (const raw of parser.push(decoder.decode(chunk, { stream: true }))) emit(onEvent(raw));
+    },
+    close: () => translator.close(),
+    idle: (message) => (translator.finished ? '' : translator.close(message)),
+  });
+}
+
+export function answerWhole(res: ServerResponse, frames: string, key: string): void {
+  const scanner = new UsageScanner(key);
+  scanner.feed(frames);
+  scanner.done();
+  const message = assembleMessage(frames);
+  const kind = isRecord(message.error) ? String(message.error.type) : '';
+  res.writeHead(message.type === 'error' ? (STATUS_OF[kind] ?? 502) : 200, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(message));
+}
+
+export const estimateTokens = (body: Record<string, unknown>): number => Math.ceil(JSON.stringify(body).length / 4);
+
+export function countTokens(res: ServerResponse, body: Record<string, unknown>): void {
+  res.writeHead(200, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ input_tokens: estimateTokens(body) }));
+}