opencode-ufr 0.2.0

package/src/cli/index.ts

@@ -0,0 +1,93 @@
+import { parseArgs } from "node:util"
+import type { FetchLike } from "../daemon/catalog-source"
+import { type Paths, resolvePaths } from "../shared/paths"
+import { KeyringStore, type SecretStore } from "../shared/secrets"
+import { cmdCatalogDiff } from "./catalog"
+import { cmdConnect } from "./connect"
+import { type Io, terminalIo } from "./io"
+import { cmdKeys, cmdLogin } from "./keys"
+import { cmdStats } from "./stats"
+import { cmdStatus } from "./status"
+import { cmdStop } from "./stop"
+
+export type CliDeps = {
+  paths: Paths
+  secrets: SecretStore
+  io: Io
+  fetch: FetchLike
+  now: () => number
+  runOpencode: (args: string[]) => Promise<number>
+}
+
+const HELP = `ufr — opencode-ufr gateway
+
+  ufr connect                      set everything up in one call: API keys
+                                   [--keys "<k1>,<k2>"] (comma/newline separated,
+                                   whitespace filtered), optional uni login for the
+                                   built-in VPN [--login <u> --password <p>]
+  ufr keys list | remove <alias> | test [alias]   manage stored keys
+  ufr login show | remove          the uni login for the built-in VPN
+  ufr status                       gateway, keys, limits, breakers, spend today
+  ufr stats [--days N]             requests, tokens and cost (default: today)
+  ufr catalog diff                 UFR's model list vs. models.json
+  ufr stop                         stop the gateway (opencode starts it again)
+
+UFR needs the uni VPN off campus: https://wiki.uni-freiburg.de/rz/doku.php?id=vpn
+`
+
+async function runOpencode(args: string[]): Promise<number> {
+  const p = Bun.spawn(["opencode", ...args], { stdio: ["inherit", "inherit", "inherit"] })
+  return await p.exited
+}
+
+export async function main(argv: string[], partial: Partial<CliDeps> = {}): Promise<number> {
+  const d: CliDeps = {
+    paths: resolvePaths(),
+    secrets: new KeyringStore(),
+    io: terminalIo(),
+    fetch: (u, i) => fetch(u, i),
+    now: Date.now,
+    runOpencode,
+    ...partial,
+  }
+  const [cmd, ...rest] = argv
+  try {
+    switch (cmd) {
+      case "connect":
+        return await cmdConnect(d, rest)
+      case "keys":
+        return await cmdKeys(d, rest)
+      case "login":
+        return await cmdLogin(d, rest)
+      case "status":
+        return await cmdStatus(d)
+      case "stats": {
+        const { values } = parseArgs({ args: rest, options: { days: { type: "string", default: "1" } } })
+        const days = Number(values.days)
+        if (!Number.isFinite(days) || days <= 0) {
+          d.io.err("--days must be a positive number\n")
+          return 2
+        }
+        return await cmdStats(d, days)
+      }
+      case "catalog":
+        if (rest[0] === "diff") return await cmdCatalogDiff(d)
+        d.io.err("usage: ufr catalog diff\n")
+        return 2
+      case "stop":
+        return await cmdStop(d)
+      case undefined:
+      case "help":
+      case "--help":
+      case "-h":
+        d.io.out(HELP)
+        return 0
+      default:
+        d.io.err(`unknown command: ${cmd}\n\n${HELP}`)
+        return 2
+    }
+  } catch (e) {
+    d.io.err(`error: ${(e as Error).message}\n`)
+    return 1
+  }
+}

package/src/cli/io.ts

@@ -0,0 +1,98 @@
+import { createInterface } from "node:readline/promises"
+import type { Readable, Writable } from "node:stream"
+
+export type Io = {
+  out(s: string): void
+  err(s: string): void
+  isTTY: boolean
+  prompt(question: string, o?: { secret?: boolean }): Promise<string>
+  confirm(question: string): Promise<boolean>
+}
+
+export function terminalIo(): Io {
+  return {
+    out: (s) => void process.stdout.write(s),
+    err: (s) => void process.stderr.write(s),
+    isTTY: process.stdin.isTTY === true,
+    prompt: (q, o) => (o?.secret ? (process.stdin.isTTY ? readSecret(q) : readPipedSecret(q)) : readLine(q)),
+    // Non-interactive sessions (scripts, pipes) can never answer a question:
+    // treat a confirm as "no" immediately instead of waiting on stdin forever.
+    confirm: async (q) =>
+      process.stdin.isTTY === true && /^(y|yes|j|ja)$/i.test((await readLine(`${q} [y/N] `)).trim()),
+  }
+}
+
+/** Testable variant: answers one prompt from a closed/ended stream with "" instead of hanging. */
+export function readLineFrom(q: string, input: Readable, output: Writable): Promise<string> {
+  return readLine(q, input, output)
+}
+
+async function readLine(
+  q: string,
+  input: Readable = process.stdin,
+  output: Writable = process.stdout,
+): Promise<string> {
+  const rl = createInterface({ input, output })
+  try {
+    // Resolve on close as well: with stdin already at EOF (piped input exhausted,
+    // no terminal) question() would otherwise never settle and hang the CLI.
+    return await new Promise<string>((resolve) => {
+      rl.once("close", () => resolve(""))
+      rl.question(q).then(resolve, () => resolve(""))
+    })
+  } finally {
+    rl.close()
+  }
+}
+
+/**
+ * A secret piped in (stdin not a TTY): read one line with readline in non-terminal
+ * mode, which never writes the line back. The question goes to stderr, not to the
+ * output that readLine's terminal mode would echo the key into.
+ */
+export function readPipedSecret(q: string, input: Readable = process.stdin, err: Writable = process.stderr): Promise<string> {
+  err.write(q)
+  const rl = createInterface({ input, terminal: false })
+  return new Promise((resolve) => {
+    let done = false
+    const finish = (line: string) => {
+      if (done) return
+      done = true
+      rl.close()
+      err.write("\n")
+      resolve(line)
+    }
+    rl.once("line", finish)
+    rl.once("close", () => finish(""))
+  })
+}
+
+/** Read one line without echo — for API keys. */
+function readSecret(q: string): Promise<string> {
+  process.stdout.write(q)
+  const stdin = process.stdin
+  return new Promise((resolve) => {
+    let buf = ""
+    const finish = () => {
+      stdin.setRawMode(false)
+      stdin.pause()
+      stdin.off("data", onData)
+      process.stdout.write("\n")
+      resolve(buf)
+    }
+    const onData = (d: Buffer) => {
+      for (const ch of d.toString("utf8")) {
+        if (ch === "\r" || ch === "\n") return finish()
+        if (ch === "\u0003") {
+          stdin.setRawMode(false)
+          process.exit(130)
+        }
+        if (ch === "\u007f" || ch === "\b") buf = buf.slice(0, -1)
+        else buf += ch
+      }
+    }
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.on("data", onData)
+  })
+}

package/src/cli/keys.ts

@@ -0,0 +1,95 @@
+import { loadConfig, saveConfig } from "../shared/config"
+import type { Paths } from "../shared/paths"
+import { VPN_PASS, VPN_USER } from "../shared/secrets"
+import { daemonRequest } from "./daemon-client"
+import type { FetchLike } from "../daemon/catalog-source"
+import type { CliDeps } from "./index"
+import { type Check, checkKey } from "./ufr-check"
+
+const LABEL: Record<Check | "missing", string> = {
+  ok: "ok",
+  invalid: "INVALID (UFR says 401)",
+  vpn: "cannot check — not on the uni VPN",
+  unreachable: "cannot check — UFR unreachable",
+  rate_limited: "ok (currently rate-limited)",
+  missing: "MISSING in keyring",
+}
+
+/** A running gateway read its keys at start: stop it while idle so opencode starts it with the new set. */
+export async function applyKeyChange(d: { paths: Paths; fetch: FetchLike; log: (m: string) => void }): Promise<void> {
+  const res = await daemonRequest(d.paths, d.fetch, "/v1/_status")
+  if (!res?.ok) return // not running — it reads the keys when opencode next starts it
+  const { inFlight } = (await res.json()) as { inFlight?: number }
+  if (inFlight !== 0) {
+    d.log("the gateway is answering a request right now — run `ufr stop` later so it picks up the new keys")
+    return
+  }
+  const stopped = await daemonRequest(d.paths, d.fetch, "/v1/_shutdown", "POST")
+  d.log(stopped?.ok ? "gateway stopped — it restarts with the new keys when opencode next needs it"
+    : "could not stop the gateway — run `ufr stop` so it picks up the new keys")
+}
+
+export async function cmdKeys(d: CliDeps, args: string[]): Promise<number> {
+  const [sub, ...rest] = args
+  const cfg = await loadConfig(d.paths.configFile)
+  switch (sub) {
+    case "list": {
+      if (cfg.keys.length === 0) {
+        d.io.out("no keys — add them with `ufr connect`\n")
+        return 0
+      }
+      for (const a of cfg.keys) d.io.out(`${a}\t${(await d.secrets.get(a)) ? "stored" : LABEL.missing}\n`)
+      return 0
+    }
+    case "remove": {
+      const alias = rest[0]
+      if (!alias) {
+        d.io.err("usage: ufr keys remove <alias>\n")
+        return 2
+      }
+      await d.secrets.delete(alias)
+      const had = cfg.keys.includes(alias)
+      cfg.keys = cfg.keys.filter((k) => k !== alias)
+      await saveConfig(d.paths.configFile, cfg)
+      d.io.out(`removed "${alias}"\n`)
+      if (had) await applyKeyChange({ paths: d.paths, fetch: d.fetch, log: (m) => d.io.out(m + "\n") })
+      return 0
+    }
+    case "test": {
+      let bad = 0
+      for (const a of rest[0] ? [rest[0]] : cfg.keys) {
+        const key = await d.secrets.get(a)
+        const r: Check | "missing" = key ? await checkKey(d.fetch, cfg.upstream.baseUrl, key) : "missing"
+        if (r !== "ok" && r !== "rate_limited") bad++
+        d.io.out(`${a}\t${LABEL[r]}\n`)
+      }
+      return bad ? 1 : 0
+    }
+    default:
+      d.io.err("usage: ufr keys list | remove <alias> | test [alias]\n")
+      return 2
+  }
+}
+
+/** ufr login — inspect or remove the stored uni login (set it with `ufr connect`). */
+export async function cmdLogin(d: CliDeps, args: string[]): Promise<number> {
+  const [sub] = args
+  if (sub === "remove") {
+    await d.secrets.delete(VPN_USER)
+    await d.secrets.delete(VPN_PASS)
+    d.io.out("removed the stored uni login\n")
+    return 0
+  }
+  if (sub === "show" || sub === undefined) {
+    const u = await d.secrets.get(VPN_USER)
+    const p = await d.secrets.get(VPN_PASS)
+    if (!u) {
+      d.io.out("no uni login stored — set it with `ufr connect --login <user> --password <pass> --keys …`\n")
+      return 1
+    }
+    d.io.out(`${u}\tpassword ${p ? "stored" : "MISSING in keyring"}\n`)
+    return p ? 0 : 1
+  }
+  d.io.err("usage: ufr login show | remove\n")
+  return 2
+}

package/src/cli/stats.ts

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs"
+import { Stats, type SummaryRow } from "../daemon/stats"
+import { loadConfig } from "../shared/config"
+import { startOfLocalDay } from "../shared/time"
+import type { CliDeps } from "./index"
+
+function table(label: string, rows: SummaryRow[], budget: number, showPct: boolean): string {
+  if (rows.length === 0) return `${label}: no requests\n`
+  const lines = rows.map((r) => {
+    const cost = `$${r.costUsd.toFixed(4)}${r.unpriced ? ` +${r.unpriced} unpriced` : ""}`
+    const pct = showPct && budget > 0 ? `  ${((r.costUsd / budget) * 100).toFixed(2)}% of $${budget} (est.)` : ""
+    return `  ${r.name.padEnd(36)} ${String(r.requests).padStart(6)} req ${String(r.errors).padStart(5)} err ` +
+      `${String(r.promptTokens).padStart(11)} in ${String(r.completionTokens).padStart(9)} out  ${cost}${pct}`
+  })
+  return `${label}\n${lines.join("\n")}\n`
+}
+
+export async function cmdStats(d: CliDeps, days: number): Promise<number> {
+  if (!existsSync(d.paths.statsDb)) {
+    d.io.out("no stats yet — the gateway records requests once opencode uses it\n")
+    return 0
+  }
+  const cfg = await loadConfig(d.paths.configFile)
+  const stats = new Stats(d.paths.statsDb)
+  try {
+    const today = days === 1
+    const since = today ? startOfLocalDay(d.now()) : d.now() - days * 86_400_000
+    const { byModel, byKey } = stats.summary(since)
+    d.io.out(`${today ? "today (since local midnight)" : `last ${days} days`}\n\n`)
+    d.io.out(table("per model", byModel, cfg.dailyBudgetUsd, false))
+    d.io.out("\n")
+    d.io.out(table("per key", byKey, cfg.dailyBudgetUsd, today))
+    return 0
+  } finally {
+    stats.close()
+  }
+}

package/src/cli/status.ts

@@ -0,0 +1,48 @@
+import type { StatusJson } from "../daemon/daemon"
+import { loadConfig } from "../shared/config"
+import { VPN_PASS, VPN_USER } from "../shared/secrets"
+import { daemonRequest } from "./daemon-client"
+import type { CliDeps } from "./index"
+
+const ago = (ms: number) =>
+  ms < 60_000 ? `${Math.round(ms / 1000)}s` : ms < 3_600_000 ? `${Math.round(ms / 60_000)}m` : `${Math.round(ms / 3_600_000)}h`
+
+export function formatStatus(s: StatusJson): string {
+  const L: string[] = []
+  L.push(`gateway   v${s.version}  pid ${s.pid}  127.0.0.1:${s.port}  up ${ago(s.uptimeMs)}  in flight ${s.inFlight}`)
+  if (s.upstream.ok === false) L.push(`UFR       NOT reachable — ${s.upstream.message}`)
+  else if (s.upstream.ok) L.push(`UFR       reachable (checked ${ago(s.now - s.upstream.at)} ago)`)
+  else L.push("UFR       not checked yet")
+  if (s.keys.length === 0) L.push("keys      none — run `ufr connect`")
+  s.keys.forEach((k, i) => {
+    const spend = s.spendToday[k.alias] ?? 0
+    const pct = s.dailyBudgetUsd > 0 ? ` (${((spend / s.dailyBudgetUsd) * 100).toFixed(2)}% of $${s.dailyBudgetUsd}, est.)` : ""
+    const state = k.invalid ? "  INVALID" : k.blockedForMs > 0 ? `  cooling down ${ago(k.blockedForMs)}` : ""
+    L.push(`${i === 0 ? "keys      " : "          "}${k.alias}  ${k.used}/${k.cap} per 60s  today $${spend.toFixed(4)}${pct}${state}`)
+  })
+  L.push(`pool      ${s.pool.enabled ? `${s.pool.inWindow}/${s.pool.cap} per hour` : "limiter off"}`)
+  const open = Object.entries(s.breakers).filter(([, b]) => b.state !== "closed")
+  L.push(open.length === 0 ? "breakers  all closed"
+    : `breakers  ${open.map(([g, b]) => `${g} ${b.state} (rung ${b.level + 1}, ${ago(b.retryAfterMs)} left)`).join(", ")}`)
+  L.push(`catalog   ${s.catalog.models} models; models.json from ${s.catalog.source}, UFR list from ${s.catalog.ufrSource}` +
+    (s.catalog.loadedAt ? ` (loaded ${ago(s.now - s.catalog.loadedAt)} ago)` : ""))
+  if (s.vpn) L.push(`vpn       ${s.vpn.mode} — ${s.vpn.detail}`)
+  for (const w of s.catalog.warnings) L.push(`warning   ${w}`)
+  return L.join("\n") + "\n"
+}
+
+export async function cmdStatus(d: CliDeps): Promise<number> {
+  const user = await d.secrets.get(VPN_USER)
+  const pass = await d.secrets.get(VPN_PASS)
+  const vpnLine = user
+    ? `vpn       login ${user} (password ${pass ? "stored" : "MISSING in keyring"})\n`
+    : "vpn       login not stored — off campus the built-in VPN needs one (ufr login add <user>)\n"
+  const res = await daemonRequest(d.paths, d.fetch, "/v1/_status")
+  if (!res || !res.ok) {
+    const cfg = await loadConfig(d.paths.configFile)
+    d.io.out(`gateway   not running (opencode starts it)\nkeys      ${cfg.keys.join(", ") || "none — run `ufr connect`"}\n${vpnLine}`)
+    return 0
+  }
+  d.io.out(formatStatus((await res.json()) as StatusJson) + vpnLine)
+  return 0
+}

package/src/cli/stop.ts

@@ -0,0 +1,8 @@
+import { daemonRequest } from "./daemon-client"
+import type { CliDeps } from "./index"
+
+export async function cmdStop(d: CliDeps): Promise<number> {
+  const res = await daemonRequest(d.paths, d.fetch, "/v1/_shutdown", "POST")
+  d.io.out(res?.ok ? "gateway stopping — opencode starts it again when needed\n" : "gateway not running\n")
+  return 0
+}

package/src/cli/ufr-check.ts

@@ -0,0 +1,43 @@
+import type { FetchLike } from "../daemon/catalog-source"
+import { isVpnPage } from "../shared/vpn"
+
+export type Check = "ok" | "invalid" | "vpn" | "unreachable" | "rate_limited"
+
+async function classify(res: Response): Promise<Check> {
+  const type = res.headers.get("content-type") ?? ""
+  if (type.includes("text/html")) {
+    const html = await res.text().catch(() => "")
+    return isVpnPage(html) ? "vpn" : "unreachable"
+  }
+  if (res.status >= 300 && res.status < 400) return "unreachable"
+  if (res.status === 401 || res.status === 403) return "invalid"
+  if (res.status === 429) return "rate_limited"
+  return res.ok ? "ok" : "unreachable"
+}
+
+export async function checkKey(f: FetchLike, baseUrl: string, key: string): Promise<Check> {
+  try {
+    return await classify(await f(`${baseUrl}/models`, {
+      headers: { Authorization: `Bearer ${key}` },
+      redirect: "manual",
+      signal: AbortSignal.timeout(15_000),
+    }))
+  } catch {
+    return "unreachable"
+  }
+}
+
+/** One minimal chat call (max_tokens 1) — proves the whole path incl. the VPN. */
+export async function checkChat(f: FetchLike, baseUrl: string, key: string, model: string): Promise<Check> {
+  try {
+    return await classify(await f(`${baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: "user", content: "Hi" }] }),
+      redirect: "manual",
+      signal: AbortSignal.timeout(60_000),
+    }))
+  } catch {
+    return "unreachable"
+  }
+}

package/src/daemon/breaker.ts

@@ -0,0 +1,146 @@
+export type BreakerState = "closed" | "open" | "half_open"
+export type BreakerOptions = { tripThreshold: number; ladderMs: number[]; probeTimeoutMs: number; now: () => number }
+export type BreakerSnapshot = { level: number; openUntil: number; consecutive: number; trips: number }
+
+/**
+ * Per-model-group breaker (port of the author's former self-hosted LiteLLM
+ * proxy's BreakerCore). UFR walls model groups for hours and every request
+ * made while walled restarts the clock, so after tripThreshold rate-limited
+ * *client requests* the group goes quiet for an escalating time.
+ */
+export class Breaker {
+  consecutive = 0
+  level = 0
+  openUntil = 0
+  trips = 0
+  rejected = 0
+  private probeInFlight = false
+  private probeIssuedAt = 0
+
+  constructor(private readonly o: BreakerOptions) {
+    if (o.tripThreshold < 1) throw new Error("tripThreshold must be >= 1")
+    if (o.ladderMs.length === 0) throw new Error("ladder must not be empty")
+  }
+
+  state(): BreakerState {
+    if (this.openUntil === 0) return "closed"
+    return this.o.now() >= this.openUntil ? "half_open" : "open"
+  }
+
+  retryAfterMs(): number {
+    return Math.max(0, this.openUntil - this.o.now())
+  }
+
+  allow(): { allowed: boolean; retryAfterMs: number } {
+    let state = this.state()
+    if (state === "closed") return { allowed: true, retryAfterMs: 0 }
+    // A probe whose outcome never came back (attributed to another group after
+    // a redirect) must not wedge this group in half-open forever.
+    if (this.probeInFlight && this.o.now() - this.probeIssuedAt > this.o.probeTimeoutMs) {
+      this.probeInFlight = false
+      this.open(this.level + 1)
+      state = this.state()
+    }
+    if (state === "half_open" && !this.probeInFlight) {
+      this.probeInFlight = true
+      this.probeIssuedAt = this.o.now()
+      return { allowed: true, retryAfterMs: 0 }
+    }
+    this.rejected++
+    return { allowed: false, retryAfterMs: this.retryAfterMs() || 5_000 }
+  }
+
+  onSuccess(): void {
+    this.consecutive = 0
+    this.level = 0
+    this.openUntil = 0
+    this.probeInFlight = false
+    this.probeIssuedAt = 0
+  }
+
+  onRateLimited(): void {
+    const wasProbing = this.probeInFlight
+    this.probeInFlight = false
+    this.consecutive++
+    if (wasProbing) {
+      this.open(this.level + 1)
+      return
+    }
+    if (this.state() === "open") return // was already in flight when we tripped
+    if (this.consecutive >= this.o.tripThreshold) {
+      // Once the ladder is engaged it keeps climbing (regression 2026-09-21).
+      this.open(this.openUntil ? this.level + 1 : 0)
+    }
+  }
+
+  /** Timeouts, context errors, 5xx: no evidence of a wall. Clears a probe. */
+  onOtherFailure(): void {
+    this.probeInFlight = false
+  }
+
+  private open(level: number): void {
+    this.level = Math.min(level, this.o.ladderMs.length - 1)
+    this.openUntil = this.o.now() + this.o.ladderMs[this.level]!
+    this.consecutive = 0
+    this.trips++
+  }
+
+  snapshot(): BreakerSnapshot {
+    return { level: this.level, openUntil: this.openUntil, consecutive: this.consecutive, trips: this.trips }
+  }
+
+  restore(s: BreakerSnapshot): void {
+    this.level = s.level
+    this.openUntil = s.openUntil
+    this.consecutive = s.consecutive
+    this.trips = s.trips
+  }
+}
+
+export class BreakerRegistry {
+  private readonly groups = new Map<string, Breaker>()
+
+  constructor(private readonly o: BreakerOptions) {}
+
+  get(group: string): Breaker {
+    let b = this.groups.get(group)
+    if (!b) {
+      b = new Breaker(this.o)
+      this.groups.set(group, b)
+    }
+    return b
+  }
+
+  /** First group that admits a request. Consumes a half-open probe slot on it. */
+  firstAvailable(groups: string[]): string | null {
+    for (const g of groups) if (this.get(g).allow().allowed) return g
+    return null
+  }
+
+  minRetryAfterMs(groups: string[]): number {
+    return Math.min(...groups.map((g) => this.get(g).retryAfterMs() || 5_000))
+  }
+
+  openGroups(): string[] {
+    return [...this.groups]
+      .filter(([, b]) => b.state() === "open")
+      .map(([g]) => g)
+      .sort()
+  }
+
+  snapshot(): Record<string, BreakerSnapshot> {
+    return Object.fromEntries(
+      [...this.groups].filter(([, b]) => b.openUntil !== 0 || b.consecutive > 0).map(([g, b]) => [g, b.snapshot()]),
+    )
+  }
+
+  restore(map: Record<string, BreakerSnapshot>): void {
+    for (const [g, s] of Object.entries(map)) this.get(g).restore(s)
+  }
+
+  states(): Record<string, { state: BreakerState; level: number; retryAfterMs: number }> {
+    return Object.fromEntries(
+      [...this.groups].map(([g, b]) => [g, { state: b.state(), level: b.level, retryAfterMs: b.retryAfterMs() }]),
+    )
+  }
+}

package/src/daemon/catalog-source.ts

@@ -0,0 +1,85 @@
+import { fileURLToPath } from "node:url"
+import { readJson, readText, writeFileAtomic } from "../shared/fs"
+import { type ModelsFile, validateModelsFile } from "../shared/models-file"
+import { VPN_MESSAGE, isVpnPage } from "../shared/vpn"
+import { type UfrModel, parseUfrModels } from "./catalog"
+
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>
+export type ModelsSource = "remote" | "cache" | "bundled"
+
+export const BUNDLED_MODELS = fileURLToPath(new URL("../../models.json", import.meta.url))
+
+/** models.json: remote (ETag) → last good cache → copy shipped in the package. */
+export async function loadModelsFile(o: {
+  url: string
+  cachePath: string
+  etagPath: string
+  bundledPath?: string
+  fetch: FetchLike
+  log: (m: string) => void
+}): Promise<{ file: ModelsFile; source: ModelsSource }> {
+  const cached = await readJson(o.cachePath)
+  const etag = cached ? (await readText(o.etagPath))?.trim() : undefined
+  try {
+    const res = await o.fetch(o.url, {
+      headers: etag ? { "If-None-Match": etag } : {},
+      signal: AbortSignal.timeout(15_000),
+    })
+    if (res.status === 304 && cached) return { file: validateModelsFile(cached), source: "remote" }
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const text = await res.text()
+    const file = validateModelsFile(JSON.parse(text)) // validate before it can replace a good cache
+    await writeFileAtomic(o.cachePath, text)
+    const tag = res.headers.get("etag")
+    if (tag) await writeFileAtomic(o.etagPath, tag)
+    return { file, source: "remote" }
+  } catch (e) {
+    o.log(`models.json: remote copy unavailable or invalid (${(e as Error).message}) — using the ${cached ? "cached" : "bundled"} copy`)
+  }
+  if (cached) {
+    try {
+      return { file: validateModelsFile(cached), source: "cache" }
+    } catch (e) {
+      o.log(`models.json: cached copy invalid (${(e as Error).message})`)
+    }
+  }
+  const bundled: unknown = JSON.parse(await Bun.file(o.bundledPath ?? BUNDLED_MODELS).text())
+  return { file: validateModelsFile(bundled), source: "bundled" }
+}
+
+/** UFR's own model list (needs the VPN like every UFR path); last good list is cached. */
+export async function loadUfrModels(o: {
+  baseUrl: string
+  key: string | null
+  cachePath: string
+  fetch: FetchLike
+  log: (m: string) => void
+}): Promise<{ models: UfrModel[]; source: "remote" | "cache"; error: string | null }> {
+  let error: string
+  if (!o.key) {
+    error = "no key configured"
+  } else {
+    try {
+      const res = await o.fetch(`${o.baseUrl}/models`, {
+        headers: { Authorization: `Bearer ${o.key}` },
+        signal: AbortSignal.timeout(20_000),
+        redirect: "manual",
+      })
+      const type = res.headers.get("content-type") ?? ""
+      if (type.includes("text/html")) {
+        const html = await res.text()
+        throw new Error(isVpnPage(html) ? VPN_MESSAGE : `HTML instead of JSON (HTTP ${res.status})`)
+      }
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const models = parseUfrModels(await res.json())
+      if (models.length === 0) throw new Error("UFR returned an empty model list")
+      await writeFileAtomic(o.cachePath, JSON.stringify(models))
+      return { models, source: "remote", error: null }
+    } catch (e) {
+      error = (e as Error).message
+    }
+  }
+  o.log(`UFR /api/models: ${error} — using the cached model list`)
+  const cached = await readJson(o.cachePath)
+  return { models: Array.isArray(cached) ? (cached as UfrModel[]) : [], source: "cache", error }
+}