opencode-ufr 0.2.0

package/src/daemon/main.ts

@@ -0,0 +1,18 @@
+import { resolvePaths } from "../shared/paths"
+import { KeyringStore } from "../shared/secrets"
+import { AlreadyRunningError, startDaemon } from "./daemon"
+import { createLogger } from "./log"
+
+const paths = resolvePaths()
+const log = createLogger(paths.logFile)
+try {
+  const d = await startDaemon({ paths, secrets: new KeyringStore(), log, onStopped: () => process.exit(0) })
+  for (const sig of ["SIGINT", "SIGTERM"] as const) process.on(sig, () => void d.stop())
+} catch (e) {
+  if (e instanceof AlreadyRunningError) {
+    log("another daemon is already running — exiting")
+    process.exit(0)
+  }
+  log(`fatal: ${(e as Error).message}`)
+  process.exit(1)
+}

package/src/daemon/model.ts

@@ -0,0 +1,15 @@
+/** USD per 1M tokens. UFR bills prefix-cached input in full (measured 2026-09-28). */
+export type ModelPrice = { input: number; output: number; cacheRead: number; cacheWrite: number }
+
+export type Model = {
+  id: string
+  name: string
+  tier: "free" | "paid"
+  vision: boolean
+  tools: boolean
+  context: number
+  maxOutput: number
+  price: ModelPrice | null
+  hasEntry: boolean
+  hidden: boolean
+}

package/src/daemon/router.ts

@@ -0,0 +1,392 @@
+import type { Config } from "../shared/config"
+import { errorResponse } from "../shared/errors"
+import type { BreakerRegistry } from "./breaker"
+import { type Catalog, resolveModel } from "./catalog"
+import type { KeyPool } from "./keypool"
+import { type Stats, costUsd } from "./stats"
+import type { Transport } from "./transport"
+import { type UpstreamResult, callUpstream } from "./upstream"
+import type { SlidingWindow } from "./window"
+
+export type RouterDeps = {
+  config: Config
+  catalog: () => Catalog
+  keys: KeyPool
+  pool: SlidingWindow
+  breakers: BreakerRegistry
+  stats: Stats
+  transport: Transport
+  now: () => number
+  sleep: (ms: number, signal?: AbortSignal) => Promise<void>
+  onUpstream?: (ok: boolean, message: string) => void
+}
+
+type Usage = { prompt: number; completion: number }
+type LoopOk = { ok: true; response: Response; model: string; keyAlias: string; attempts: number; upstreamAbort?: AbortController }
+type LoopFail = { ok: false; response: Response; model: string; keyAlias: string | null; attempts: number; errorType: string }
+
+export function usageOf(json: unknown): Usage | null {
+  const u = (json as { usage?: { prompt_tokens?: number; completion_tokens?: number } } | null)?.usage
+  return u ? { prompt: u.prompt_tokens ?? 0, completion: u.completion_tokens ?? 0 } : null
+}
+
+function addUsage(a: Usage | null, b: Usage | null): Usage | null {
+  if (!a) return b
+  if (!b) return a
+  return { prompt: a.prompt + b.prompt, completion: a.completion + b.completion }
+}
+
+/** Sums two per-call costs; null only when neither call's model had a known price. */
+function addCost(a: number | null, b: number | null): number | null {
+  if (a === null && b === null) return null
+  return (a ?? 0) + (b ?? 0)
+}
+
+type Choice = { finish_reason?: string; message?: { content?: string | null; reasoning_content?: string | null; reasoning?: string | null } }
+
+/** glm-5.2 can spend its whole budget thinking and return no text (observed 2026-09-08). */
+export function isReasoningStarved(json: unknown): boolean {
+  const c = (json as { choices?: Choice[] } | null)?.choices?.[0]
+  if (!c || c.finish_reason !== "length") return false
+  const content = (c.message?.content ?? "").trim()
+  const reasoning = (c.message?.reasoning_content ?? c.message?.reasoning ?? "").trim()
+  return content === "" && reasoning !== ""
+}
+
+export class Router {
+  private active = 0
+
+  constructor(private readonly d: RouterDeps) {}
+
+  /** Client requests being answered right now (streams count until they end). */
+  get inFlight(): number {
+    return this.active
+  }
+
+  async handleChat(body: Record<string, unknown>, signal?: AbortSignal): Promise<Response> {
+    this.active++
+    try {
+      return await this.handle(body, signal)
+    } finally {
+      this.active--
+    }
+  }
+
+  private async handle(body: Record<string, unknown>, signal?: AbortSignal): Promise<Response> {
+    const t0 = this.d.now()
+    const requested = typeof body.model === "string" ? body.model.trim() : ""
+    if (!requested) return errorResponse(400, "invalid_request", "body.model is required")
+    const cat = this.d.catalog()
+    const group = resolveModel(cat, requested)
+    const chain = [group, ...(cat.chains.get(group) ?? [])]
+
+    const target = this.d.breakers.firstAvailable(chain)
+    if (!target) {
+      return this.fail(t0, group, null, 0, false, "upstream_circuit_open",
+        errorResponse(429, "upstream_circuit_open",
+          `UFR is refusing ${group} and every fallback right now; the gateway waits instead of hammering it`,
+          this.d.breakers.minRetryAfterMs(chain)))
+    }
+
+    const slot = this.d.pool.reserve()
+    if (slot.verdict === "reject") {
+      // target's half-open probe (if any) was consumed by firstAvailable above but
+      // never gets an outcome — resolve it so the ladder doesn't escalate on a probe timeout.
+      this.d.breakers.get(target).onOtherFailure()
+      return this.fail(t0, group, null, 0, false, "upstream_pool_cap",
+        errorResponse(429, "upstream_pool_cap", `hourly cap of ${this.d.config.limits.poolPerHour} requests reached`, slot.waitMs))
+    }
+    if (slot.waitMs > 0) {
+      try {
+        await this.d.sleep(slot.waitMs, signal)
+      } catch {
+        this.d.pool.release(slot.at)
+        this.d.breakers.get(target).onOtherFailure()
+        return this.fail(t0, group, null, 0, false, "client_closed",
+          errorResponse(499, "client_closed", "client went away while waiting for a slot"))
+      }
+    }
+
+    const stream = body.stream === true
+    const max = this.d.config.limits.maxUpstreamAttempts
+    const res = await this.loop(body, group, target, stream, max, signal)
+    if (!res.ok) return this.fail(slot.at, res.model, res.keyAlias, res.attempts, true, res.errorType, res.response)
+    if (stream) return this.streamOut(slot.at, res)
+    return this.jsonOut(slot.at, body, group, res, max, signal)
+  }
+
+  /** Upstream calls for one client request: other key, next model, context hub. */
+  private async loop(
+    body: Record<string, unknown>,
+    group: string,
+    start: string,
+    stream: boolean,
+    maxAttempts: number,
+    signal?: AbortSignal,
+  ): Promise<LoopOk | LoopFail> {
+    const { config, keys, breakers } = this.d
+    const cat = this.d.catalog()
+    let model = start
+    let attempts = 0
+    let lastKey: string | null = null
+    let rateLimitedHere = false
+    let contextHopped = false
+    const tried = new Set<string>()
+    const counted = new Set<string>()
+    const giveUp = (m: string) => {
+      if (counted.has(m)) return
+      counted.add(m)
+      breakers.get(m).onRateLimited() // once per client request per group
+    }
+    const moveOn = (): boolean => {
+      const next = this.nextModel(model, group)
+      if (!next) return false
+      model = next
+      tried.clear()
+      rateLimitedHere = false
+      return true
+    }
+    const fail = (status: number, type: string, message: string, retryAfterMs?: number): LoopFail => ({
+      ok: false,
+      response: errorResponse(status, type, message, retryAfterMs),
+      model,
+      keyAlias: lastKey,
+      attempts,
+      errorType: type,
+    })
+
+    while (attempts < maxAttempts) {
+      if (signal?.aborted) {
+        breakers.get(model).onOtherFailure() // model's probe (if any) got no outcome
+        return fail(499, "client_closed", "client went away")
+      }
+      const k = keys.acquire(tried)
+      if (k.kind === "none") {
+        if (k.reason === "no_keys") {
+          breakers.get(model).onOtherFailure() // model's probe (if any) got no outcome
+          return fail(401, "no_keys", "no valid UFR API key configured — run `ufr keys add <alias>`")
+        }
+        if (k.reason === "exhausted") {
+          breakers.get(model).onOtherFailure() // model's probe (if any) got no outcome
+          return fail(429, "key_pool_exhausted",
+            `every UFR key is at its limit of ${config.limits.keyRpm} requests per ${config.limits.keyWindowS} s`, k.retryAfterMs)
+        }
+        // all_tried: every usable key already failed on this model
+        if (rateLimitedHere) giveUp(model)
+        if (!moveOn()) break
+        continue
+      }
+      if (k.waitMs > 0) {
+        try {
+          await this.d.sleep(k.waitMs, signal)
+        } catch {
+          keys.release(k.alias, k.at)
+          breakers.get(model).onOtherFailure() // model's probe (if any) got no outcome
+          return fail(499, "client_closed", "client went away while waiting for a key")
+        }
+      }
+      attempts++
+      tried.add(k.alias)
+      lastKey = k.alias
+      const upstreamBody: Record<string, unknown> = { ...body, model }
+      if (stream) {
+        upstreamBody.stream_options = { ...((body.stream_options as Record<string, unknown> | undefined) ?? {}), include_usage: true }
+      }
+      // Bun's fetch does not propagate a body reader's cancel() into aborting the
+      // underlying request — give streaming attempts their own controller so
+      // streamOut can actually cancel UFR when the client goes away.
+      const upstreamAbort = stream ? new AbortController() : null
+      const attemptSignal = upstreamAbort ? (signal ? AbortSignal.any([signal, upstreamAbort.signal]) : upstreamAbort.signal) : signal
+      let r: UpstreamResult
+      try {
+        r = await callUpstream({
+          transport: this.d.transport,
+          baseUrl: config.upstream.baseUrl,
+          key: k.secret,
+          body: upstreamBody,
+          timeoutMs: config.upstream.requestTimeoutS * 1000,
+          signal: attemptSignal,
+          stream,
+        })
+      } catch (e) {
+        breakers.get(model).onOtherFailure() // model's probe (if any) got no outcome
+        if (signal?.aborted) return fail(499, "client_closed", "client went away")
+        // Not the client: something else escaped callUpstream (e.g. the connection
+        // dropped while the error body was read) — an upstream failure.
+        return fail(503, "transport_unreachable", `UFR call failed (${e instanceof Error ? e.message : String(e)})`)
+      }
+      switch (r.kind) {
+        case "ok":
+          breakers.get(model).onSuccess()
+          this.d.onUpstream?.(true, "")
+          return { ok: true, response: r.response, model, keyAlias: k.alias, attempts, upstreamAbort: upstreamAbort ?? undefined }
+        case "rate_limited":
+          keys.onRateLimited(k.alias, model)
+          rateLimitedHere = true
+          if (tried.size >= Math.min(2, keys.size)) {
+            giveUp(model)
+            // At the attempt cap, don't advance to (and consume the probe of) a model
+            // that will never actually be called — let the while-condition end the loop
+            // and report the failure under the model that was really tried.
+            if (attempts < maxAttempts && !moveOn()) {
+              return fail(429, "upstream_rate_limited", `UFR rate-limited ${group} on every key and fallback tried`)
+            }
+          }
+          continue
+        case "auth_invalid":
+          keys.onInvalid(k.alias)
+          continue
+        case "context_overflow": {
+          // UFR answered this model with its own 400 — not a wall, so this resolves
+          // its probe (if any) as evidence rather than leaving it to time out.
+          breakers.get(model).onOtherFailure()
+          const hub = cat.contextChains.get(model)?.[0]
+          // The hub has its own breaker; at the attempt cap it would never be called,
+          // so don't take (and wedge) its half-open probe.
+          if (hub && !contextHopped && attempts < maxAttempts && breakers.get(hub).allow().allowed) {
+            contextHopped = true
+            model = hub
+            tried.clear()
+            rateLimitedHere = false
+            continue
+          }
+          return { ok: false, response: new Response(r.body, { status: r.status, headers: { "content-type": "application/json" } }),
+            model, keyAlias: k.alias, attempts, errorType: "context_overflow" }
+        }
+        case "unreachable":
+          breakers.get(model).onOtherFailure()
+          this.d.onUpstream?.(false, r.message)
+          return fail(503, "transport_unreachable", r.message)
+        case "error":
+          breakers.get(model).onOtherFailure()
+          return { ok: false, response: new Response(r.body, { status: r.status, headers: { "content-type": r.contentType } }),
+            model, keyAlias: k.alias, attempts, errorType: `upstream_${r.status}` }
+      }
+    }
+    if (rateLimitedHere) giveUp(model)
+    return fail(429, "upstream_rate_limited", `UFR rate-limited ${group}; gave up after ${attempts} upstream calls`)
+  }
+
+  private nextModel(current: string, group: string): string | null {
+    const cat = this.d.catalog()
+    const chain = [group, ...(cat.chains.get(group) ?? [])]
+    const i = chain.indexOf(current)
+    if (i < 0) return null
+    for (const m of chain.slice(i + 1)) if (this.d.breakers.get(m).allow().allowed) return m
+    return null
+  }
+
+  private async jsonOut(ts: number, body: Record<string, unknown>, group: string, res: LoopOk, max: number, signal?: AbortSignal): Promise<Response> {
+    let json: unknown = await res.response.json()
+    let usage = usageOf(json)
+    let cost = usage ? costUsd(this.priceOf(res.model), usage.prompt, usage.completion) : null
+    let attempts = res.attempts
+    let model = res.model
+    let keyAlias = res.keyAlias
+    if (isReasoningStarved(json) && attempts < max) {
+      const retry = await this.loop({ ...body, reasoning_effort: "none" }, group, res.model, false, max - attempts, signal)
+      attempts += retry.attempts
+      if (retry.ok) {
+        const again: unknown = await retry.response.json()
+        const u2 = usageOf(again)
+        // Price each call at the model it was actually answered by — a retry that
+        // falls back must not price the first call at the fallback's rate.
+        cost = addCost(cost, u2 ? costUsd(this.priceOf(retry.model), u2.prompt, u2.completion) : null)
+        usage = addUsage(usage, u2)
+        if (!isReasoningStarved(again)) {
+          json = again
+          model = retry.model
+          keyAlias = retry.keyAlias
+        }
+      }
+    }
+    this.record(ts, model, keyAlias, 200, usage, attempts, null, true, cost)
+    return Response.json(json)
+  }
+
+  private priceOf(model: string) {
+    return this.d.catalog().models.get(model)?.price ?? null
+  }
+
+  /** Byte-for-byte pass-through; records the usage chunk; cancelling cancels UFR. */
+  private streamOut(ts: number, res: LoopOk): Response {
+    const reader = res.response.body!.getReader()
+    const decoder = new TextDecoder()
+    let buf = ""
+    let usage: Usage | null = null
+    let finished = false
+    this.active++ // handleChat's own count ends when it returns; the stream keeps one until it is done
+    const finish = (errorType: string | null) => {
+      if (finished) return
+      finished = true
+      this.active--
+      this.record(ts, res.model, res.keyAlias, 200, usage, res.attempts, errorType, true)
+    }
+    const scan = (chunk: Uint8Array) => {
+      buf += decoder.decode(chunk, { stream: true })
+      let nl: number
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl).trim()
+        buf = buf.slice(nl + 1)
+        if (!line.startsWith("data:")) continue
+        const data = line.slice(5).trim()
+        if (!data || data === "[DONE]") continue
+        try {
+          const u = usageOf(JSON.parse(data))
+          if (u) usage = u
+        } catch {
+          // not JSON: pass it through untouched
+        }
+      }
+    }
+    const out = new ReadableStream<Uint8Array>({
+      pull: async (ctl) => {
+        try {
+          const { value, done } = await reader.read()
+          if (done) {
+            finish(null)
+            ctl.close()
+            return
+          }
+          scan(value)
+          ctl.enqueue(value)
+        } catch (e) {
+          finish("stream_error")
+          ctl.error(e)
+        }
+      },
+      cancel: async (reason) => {
+        finish("client_closed")
+        res.upstreamAbort?.abort() // reader.cancel() alone does not abort the upstream fetch on Bun
+        await reader.cancel(reason).catch(() => {})
+      },
+    })
+    return new Response(out, { status: 200, headers: { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-cache" } })
+  }
+
+  /** costOverride, when passed, is used as-is (e.g. a reasoning retry's own per-call sum);
+   *  otherwise cost is derived from `model`'s price, as for every other single-call outcome. */
+  private record(ts: number, model: string, keyAlias: string | null, status: number, usage: Usage | null,
+    attempts: number, errorType: string | null, poolAdmitted: boolean, costOverride?: number | null): void {
+    const cost = costOverride !== undefined ? costOverride : (usage ? costUsd(this.priceOf(model), usage.prompt, usage.completion) : null)
+    this.d.stats.record({
+      ts,
+      model,
+      keyAlias,
+      status,
+      promptTokens: usage?.prompt ?? 0,
+      completionTokens: usage?.completion ?? 0,
+      costUsd: cost,
+      latencyMs: Math.max(0, this.d.now() - ts),
+      attempts,
+      errorType,
+      poolAdmitted,
+    })
+  }
+
+  private fail(ts: number, model: string, keyAlias: string | null, attempts: number, poolAdmitted: boolean,
+    errorType: string, response: Response): Response {
+    this.record(ts, model, keyAlias, response.status, null, attempts, errorType, poolAdmitted)
+    return response
+  }
+}

package/src/daemon/server.ts

@@ -0,0 +1,54 @@
+import { errorResponse } from "../shared/errors"
+import type { Router } from "./router"
+
+export type ServerDeps = {
+  port: number
+  token: string
+  version: string
+  router: Router
+  models: () => unknown[]
+  status: () => unknown
+  onActivity: () => void
+  onShutdown: () => void
+}
+
+export function startServer(d: ServerDeps): { port: number; stop: () => void } {
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: d.port,
+    idleTimeout: 30,
+    fetch: async (req, srv) => {
+      const url = new URL(req.url)
+      if (req.method === "GET" && url.pathname === "/health") {
+        return Response.json({ ok: true, version: d.version, pid: process.pid })
+      }
+      if (req.headers.get("authorization") !== `Bearer ${d.token}`) {
+        return errorResponse(401, "unauthorized", "missing or wrong local gateway token")
+      }
+      d.onActivity()
+      const route = `${req.method} ${url.pathname}`
+      if (route === "GET /v1/models") return Response.json({ object: "list", data: d.models() })
+      if (route === "POST /v1/chat/completions") {
+        srv.timeout(req, 0) // glm-5.2 can think for minutes before the first byte
+        let body: unknown
+        try {
+          body = await req.json()
+        } catch {
+          return errorResponse(400, "invalid_request", "body must be JSON")
+        }
+        if (typeof body !== "object" || body === null || Array.isArray(body)) {
+          return errorResponse(400, "invalid_request", "body must be a JSON object")
+        }
+        return d.router.handleChat(body as Record<string, unknown>, req.signal)
+      }
+      if (route === "POST /v1/_client/heartbeat") return Response.json({ ok: true })
+      if (route === "GET /v1/_status") return Response.json(d.status())
+      if (route === "POST /v1/_shutdown") {
+        setTimeout(d.onShutdown, 20)
+        return Response.json({ ok: true })
+      }
+      return errorResponse(404, "not_found", `no route ${route}`)
+    },
+  })
+  return { port: server.port as number, stop: () => server.stop(true) }
+}

package/src/daemon/stats.ts

@@ -0,0 +1,105 @@
+import { Database } from "bun:sqlite"
+import { mkdirSync } from "node:fs"
+import { dirname } from "node:path"
+import type { ModelPrice } from "./model"
+
+export type RequestRow = {
+  ts: number
+  model: string
+  keyAlias: string | null
+  status: number
+  promptTokens: number
+  completionTokens: number
+  costUsd: number | null
+  latencyMs: number
+  attempts: number
+  errorType: string | null
+  poolAdmitted: boolean
+}
+
+export type SummaryRow = {
+  name: string
+  requests: number
+  errors: number
+  promptTokens: number
+  completionTokens: number
+  costUsd: number
+  unpriced: number
+}
+
+/** Prompt tokens are all billed at the input price — UFR has no cache discount. */
+export function costUsd(price: ModelPrice | null, promptTokens: number, completionTokens: number): number | null {
+  if (!price) return null
+  return (promptTokens * price.input + completionTokens * price.output) / 1_000_000
+}
+
+export class Stats {
+  private readonly db: Database
+
+  constructor(path: string) {
+    if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true })
+    this.db = new Database(path, { create: true })
+    if (path !== ":memory:") this.db.exec("PRAGMA journal_mode = WAL")
+    this.db.exec(`CREATE TABLE IF NOT EXISTS requests (
+      ts INTEGER NOT NULL, model TEXT NOT NULL, key_alias TEXT, status INTEGER NOT NULL,
+      prompt_tokens INTEGER NOT NULL, completion_tokens INTEGER NOT NULL, cost_usd REAL,
+      latency_ms INTEGER NOT NULL, attempts INTEGER NOT NULL, error_type TEXT, pool_admitted INTEGER NOT NULL)`)
+    this.db.exec("CREATE INDEX IF NOT EXISTS requests_ts ON requests(ts)")
+    this.db.exec("CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT NOT NULL)")
+  }
+
+  record(r: RequestRow): void {
+    this.db
+      .query(
+        `INSERT INTO requests (ts, model, key_alias, status, prompt_tokens, completion_tokens, cost_usd,
+         latency_ms, attempts, error_type, pool_admitted) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(r.ts, r.model, r.keyAlias, r.status, r.promptTokens, r.completionTokens, r.costUsd,
+        Math.round(r.latencyMs), r.attempts, r.errorType, r.poolAdmitted ? 1 : 0)
+  }
+
+  /** Admission times for rebuilding the pool window after a restart. */
+  poolAdmissionsSince(sinceTs: number): number[] {
+    const rows = this.db.query("SELECT ts FROM requests WHERE pool_admitted = 1 AND ts > ? ORDER BY ts").all(sinceTs) as { ts: number }[]
+    return rows.map((r) => r.ts)
+  }
+
+  spendByKeySince(sinceTs: number): Record<string, number> {
+    const rows = this.db
+      .query("SELECT key_alias AS k, COALESCE(SUM(cost_usd), 0) AS c FROM requests WHERE ts >= ? AND key_alias IS NOT NULL GROUP BY key_alias")
+      .all(sinceTs) as { k: string; c: number }[]
+    return Object.fromEntries(rows.map((r) => [r.k, r.c]))
+  }
+
+  summary(sinceTs: number): { byModel: SummaryRow[]; byKey: SummaryRow[] } {
+    const q = (col: string) =>
+      this.db
+        .query(
+          `SELECT ${col} AS name, COUNT(*) AS requests,
+             SUM(CASE WHEN status >= 400 THEN 1 ELSE 0 END) AS errors,
+             SUM(prompt_tokens) AS promptTokens, SUM(completion_tokens) AS completionTokens,
+             COALESCE(SUM(cost_usd), 0) AS costUsd,
+             SUM(CASE WHEN cost_usd IS NULL AND status < 400 THEN 1 ELSE 0 END) AS unpriced
+           FROM requests WHERE ts >= ? GROUP BY ${col} ORDER BY costUsd DESC, requests DESC`,
+        )
+        .all(sinceTs) as SummaryRow[]
+    return { byModel: q("model"), byKey: q("COALESCE(key_alias, '-')") }
+  }
+
+  prune(beforeTs: number): number {
+    return this.db.query("DELETE FROM requests WHERE ts < ?").run(beforeTs).changes
+  }
+
+  setKv(k: string, v: string): void {
+    this.db.query("INSERT INTO kv (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v").run(k, v)
+  }
+
+  getKv(k: string): string | null {
+    const r = this.db.query("SELECT v FROM kv WHERE k = ?").get(k) as { v: string } | null
+    return r?.v ?? null
+  }
+
+  close(): void {
+    this.db.close()
+  }
+}

package/src/daemon/transport.ts

@@ -0,0 +1,21 @@
+import type { Config } from "../shared/config"
+import type { VpnManager } from "./vpn/manager"
+
+/**
+ * How the daemon reaches UFR. "direct" only uses the OS network (user is on
+ * the campus network or their own VPN). "auto" routes through the built-in
+ * Fortinet tunnel (userspace TCP stack — no TUN, no routes, no admin rights)
+ * whenever UFR is not reachable directly.
+ */
+export type Transport = { name: string; fetch(url: string, init?: RequestInit): Promise<Response> }
+
+export const directTransport: Transport = { name: "direct", fetch: (url, init) => fetch(url, init) }
+
+export function createTransport(cfg: Config["transport"], o: { vpn?: VpnManager | null } = {}): Transport {
+  switch (cfg.type) {
+    case "direct":
+      return directTransport
+    case "auto":
+      return o.vpn?.transport() ?? directTransport
+  }
+}

package/src/daemon/upstream.ts

@@ -0,0 +1,68 @@
+import { VPN_MESSAGE, isVpnPage } from "../shared/vpn"
+import type { Transport } from "./transport"
+
+export type UpstreamResult =
+  | { kind: "ok"; response: Response }
+  | { kind: "rate_limited"; status: number; body: string }
+  | { kind: "context_overflow"; status: number; body: string }
+  | { kind: "auth_invalid"; status: number; body: string }
+  | { kind: "unreachable"; message: string }
+  | { kind: "error"; status: number; body: string; contentType: string }
+
+const CONTEXT_RE = /maximum context length|max input tokens|context length|context window|too many tokens|prompt is too long/i
+
+/** One call to UFR. Throws only if the caller's own signal aborted. */
+export async function callUpstream(o: {
+  transport: Transport
+  baseUrl: string
+  key: string
+  body: unknown
+  timeoutMs: number
+  signal?: AbortSignal
+  stream: boolean
+}): Promise<UpstreamResult> {
+  const timeout = AbortSignal.timeout(o.timeoutMs)
+  const signal = o.signal ? AbortSignal.any([o.signal, timeout]) : timeout
+  let res: Response
+  try {
+    res = await o.transport.fetch(`${o.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${o.key}`,
+        "Content-Type": "application/json",
+        Accept: o.stream ? "text/event-stream" : "application/json",
+      },
+      body: JSON.stringify(o.body),
+      signal,
+      redirect: "manual",
+    })
+  } catch (e) {
+    if (o.signal?.aborted) throw e
+    if (timeout.aborted) {
+      const message = `UFR did not answer within ${Math.round(o.timeoutMs / 1000)} s`
+      return {
+        kind: "error",
+        status: 504,
+        body: JSON.stringify({ error: { message, type: "upstream_timeout", code: 504 } }),
+        contentType: "application/json",
+      }
+    }
+    return { kind: "unreachable", message: `cannot reach UFR (${(e as Error).message}) — are you connected to the uni VPN?` }
+  }
+  const type = res.headers.get("content-type") ?? ""
+  if (res.status >= 300 && res.status < 400) {
+    // Not proof of the VPN wall (ruling R12): only UFR's HTML page below is.
+    await res.body?.cancel()
+    return { kind: "unreachable", message: `UFR answered with a redirect (HTTP ${res.status}) instead of JSON` }
+  }
+  if (type.includes("text/html")) {
+    const html = await res.text()
+    return { kind: "unreachable", message: isVpnPage(html) ? VPN_MESSAGE : `UFR answered with an HTML page (HTTP ${res.status}) instead of JSON` }
+  }
+  if (res.ok) return { kind: "ok", response: res }
+  const body = await res.text()
+  if (res.status === 429) return { kind: "rate_limited", status: 429, body }
+  if (res.status === 401 || res.status === 403) return { kind: "auth_invalid", status: res.status, body }
+  if ((res.status === 400 || res.status === 413) && CONTEXT_RE.test(body)) return { kind: "context_overflow", status: res.status, body }
+  return { kind: "error", status: res.status, body, contentType: type || "application/json" }
+}