dsh-connect-qoder 0.1.0

package/lib/index.js

@@ -0,0 +1,691 @@
+/**
+ * DSH Connect Qoder — bring locally signed-in Qoder models into DeepSeek
+ * Harness.
+ *
+ * The Qoder desktop apps (Qoder CN and the international Qoder) already hold a
+ * valid sign-in on this machine. This bundle reads that sign-in, registers one
+ * DSH provider per region, and routes each region's traffic through a private
+ * loopback shim that speaks OpenAI to pi-ai and COSY-signed Qoder on the way
+ * out.
+ *
+ * Both regions register unconditionally and independently: whichever apps are
+ * signed in produce a visible model group, and a region with no credential
+ * simply contributes no models. Nothing here starts an OAuth flow, and nothing
+ * writes to the Qoder apps' own files.
+ *
+ * @module dsh-connect-qoder
+ */
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+import { join } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import z from '@deepseek-ai/schemastery'
+import { createQoderAdapter, offPeakActive, offPeakRemaining, rateNow } from './adapter.js'
+import { createQoderShim } from './shim.js'
+import { REGIONS, loadCredential, loadEnvCredential } from './credentials.js'
+import { exchangePat, fetchModels, fetchUsage } from './upstream.js'
+
+/** Loader row id; also the plugin's identity in the composition. */
+export const name = 'llm-qoder'
+
+/** The model registry that must exist before a provider can register. */
+export const inject = ['llm']
+
+/**
+ * Settings namespace owning this plugin's section.
+ *
+ * A namespace only becomes configurable once a section is installed into it —
+ * `registerConfigurableProviders` merely *addresses* the namespace. Without the
+ * section there is no schema, so no configuration surface can render a control
+ * for this route at all.
+ */
+export const QODER_SETTINGS_NS = 'dsh-connect-qoder'
+
+/**
+ * Prefer the largest context window the catalog declares for a model.
+ *
+ * Qoder's catalog offers 200K/400K/1M for most models and flags one as its own
+ * default. This switch decides whether this plugin advertises the largest
+ * offered window or the one Qoder itself starts on.
+ */
+const USE_MAXIMUM_CONTEXT_WINDOW_FIELD = z
+  .boolean()
+  .default(false)
+  .description('Advertise each model\'s largest declared context window instead of Qoder\'s own default window')
+
+/**
+ * Per-model image-input opt-in, keyed by user-facing model id.
+ *
+ * Qoder's catalog advertises `is_vl` per model and this plugin maps it straight
+ * onto the pi-ai `input` list, so a vision model arrives already declaring
+ * image input. The user still owns the final say: an entry here overrides the
+ * catalog for one model, which is what lets a model the catalog marks text-only
+ * (or one the endpoint rejects images for) be turned off — and what lets a
+ * mislabelled model be turned on. Absent means "follow `is_vl`".
+ */
+const IMAGE_MODES = ['auto', 'on', 'off']
+
+/** One model's image preference. */
+const IMAGE_OVERRIDES_FIELD = z
+  .dict(z.union(IMAGE_MODES))
+  .default({})
+  .description('Per-model image input: "auto" follows the catalog, "on"/"off" force it')
+
+/**
+ * Which models the picker offers, per region.
+ *
+ * An **empty list means "no filter"**, not "nothing": that is the same
+ * convention the WorkBuddy bundle uses, and it is what keeps a fresh install
+ * working — a new user has saved nothing yet, and must still see every model.
+ * Once a list is non-empty it becomes an allow-list for that region.
+ *
+ * Keyed by region id (`qoder-cn`, `qoder`) so the two editions can be curated
+ * independently; the CN and global rosters share no model ids.
+ */
+const ENABLED_MODEL_IDS_FIELD = z
+  .dict(z.array(z.string()))
+  .default({})
+  .description('Per-region allow-list of model ids; an empty list shows every model')
+
+/** The plugin's whole configuration schema. */
+export const Config = z.object({
+  useMaximumContextWindow: USE_MAXIMUM_CONTEXT_WINDOW_FIELD,
+  imageOverrides: IMAGE_OVERRIDES_FIELD,
+  enabledModelIds: ENABLED_MODEL_IDS_FIELD,
+})
+
+/** The section this plugin publishes for its settings namespace. */
+const QODER_SECTION = z.object({
+  useMaximumContextWindow: USE_MAXIMUM_CONTEXT_WINDOW_FIELD,
+  imageOverrides: IMAGE_OVERRIDES_FIELD,
+  enabledModelIds: ENABLED_MODEL_IDS_FIELD,
+})
+
+/** Plugin-owned read-only route the settings card reads its model rows from. */
+const QODER_MODELS_PATH = '/plugins/dsh-connect-qoder/models'
+
+/**
+ * Plugin-owned read-only route the card reads its usage panel from.
+ *
+ * Kept separate from the model route so the panel can be refreshed on its own:
+ * quota moves with every turn, while the catalog changes rarely.
+ */
+const QODER_USAGE_PATH = '/plugins/dsh-connect-qoder/usage'
+
+/**
+ * How long a fetched usage reading stays fresh.
+ *
+ * Quota moves only when a turn runs, so a short cache keeps the panel honest
+ * without turning every card render into an upstream round trip. The refresh
+ * button bypasses it.
+ */
+const USAGE_TTL_MS = 20 * 1000
+
+/** Answer one card request. */
+function sendJson(res, status, value) {
+  const payload = JSON.stringify(value)
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) })
+  res.end(payload)
+}
+
+/**
+ * Whether a card request came from this machine.
+ *
+ * The route exposes model metadata, not credentials, but it stays loopback-only
+ * anyway: it is an internal read path for a browser page this host itself
+ * served, and a missing Origin (a same-origin GET) is the normal case.
+ */
+function loopbackRequest(req) {
+  const origin = req.headers.origin
+  if (origin === undefined) return true
+  if (typeof origin !== 'string') return false
+  try {
+    const host = new URL(origin).hostname
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1'
+  } catch {
+    return false
+  }
+}
+
+/** How long a fetched catalog stays fresh before it is refetched. */
+const CATALOG_TTL_MS = 30 * 60 * 1000
+
+/** On-disk format this reader accepts; other versions are discarded. */
+const CATALOG_FORMAT_VERSION = 1
+
+/** Plugin-owned catalog path inside the Harness home. */
+export function qoderCatalogPath(filename = '.qoder-catalog.json') {
+  return join(resolveDshHome(), filename)
+}
+
+/**
+ * The last catalog that actually loaded, per region.
+ *
+ * A restart must not drop the user to an empty model group when a good catalog
+ * was fetched minutes earlier, and a temporary upstream failure must not either.
+ * Only model metadata is stored — never a token.
+ */
+class CatalogStore {
+  constructor(region, logger) {
+    this.path = qoderCatalogPath(`.qoder-catalog.${region.id}.json`)
+    this.logger = logger
+    this.entries = []
+    this.fetchedAt = 0
+    this.load()
+  }
+
+  load() {
+    if (!existsSync(this.path)) return
+    try {
+      const parsed = JSON.parse(readFileSync(this.path, 'utf8'))
+      if (parsed?.version !== CATALOG_FORMAT_VERSION) return
+      if (!Array.isArray(parsed.entries)) return
+      this.entries = parsed.entries
+      this.fetchedAt = Number(parsed.fetchedAt) || 0
+    } catch {
+      // A damaged cache is simply ignored; the next fetch replaces it.
+    }
+  }
+
+  save() {
+    try {
+      mkdirSync(join(this.path, '..'), { recursive: true })
+      writeFileSync(
+        this.path,
+        JSON.stringify({ version: CATALOG_FORMAT_VERSION, fetchedAt: this.fetchedAt, entries: this.entries }, null, 2),
+        'utf8',
+      )
+    } catch (error) {
+      this.logger?.warn?.(`dsh-connect-qoder: could not save catalog ${this.path}`, error)
+    }
+  }
+
+  current() {
+    return this.entries
+  }
+
+  fresh() {
+    return Date.now() - this.fetchedAt < CATALOG_TTL_MS
+  }
+
+  replace(entries) {
+    this.entries = entries
+    this.fetchedAt = Date.now()
+    this.save()
+  }
+}
+
+/**
+ * A model id is the catalog display name with whitespace removed, so the id is
+ * stable and readable; the upstream key is tracked beside it for the wire.
+ */
+function modelIdFor(entry) {
+  return (entry.display_name || 'QoderModel').replace(/\s+/g, '')
+}
+
+/**
+ * Reshape one entry from {@link fetchModels} for storage and lookup.
+ *
+ * The catalog interpretation (vision, reasoning, effort support, and the
+ * always-thinking rule) already happened in `fetchModels`, so this only adds
+ * the user-facing id.
+ */
+function normalizeEntry(entry) {
+  return {
+    id: modelIdFor({ display_name: entry.name }),
+    key: entry.key,
+    name: entry.name,
+    isVL: entry.isVL === true,
+    isReasoning: entry.isReasoning === true,
+    supportsEffort: entry.supportsEffort === true,
+    alwaysThinking: entry.alwaysThinking === true,
+    effortLevels: Array.isArray(entry.effortLevels) ? entry.effortLevels : [],
+    maxInputTokens: entry.maxInputTokens ?? 0,
+    // `toPiModel` sizes each model from these two, so dropping them here (which
+    // is what happened before) made `useMaximumContextWindow` do nothing at all:
+    // with no `contextOptions` the "widest offered window" is 0, the switch has
+    // nothing to prefer, and every model falls back to `max_input_tokens` — a
+    // smaller per-request floor, not the capacity the catalog advertises. They
+    // are carried through verbatim so the setting and the picker agree.
+    defaultContextWindow: entry.defaultContextWindow ?? 0,
+    contextOptions: Array.isArray(entry.contextOptions) ? entry.contextOptions : [],
+    // The credit multiplier Qoder charges for this model. It is display-only,
+    // but the picker shows it beside the name so the cost of a choice is visible
+    // before the request is sent. `toPiModel` is what formats it.
+    priceFactor: Number(entry.priceFactor) || 0,
+  }
+}
+
+/**
+ * Owns one region: its credential, catalog, shim, adapter, and registration.
+ */
+class RegionRuntime {
+  constructor(region, ctx) {
+    this.region = region
+    this.ctx = ctx
+    this.logger = ctx.logger
+    this.catalog = new CatalogStore(region, ctx.logger)
+    this.credential = undefined
+    this.exchanged = undefined
+    this.refreshTimer = undefined
+    /** Last usage reading and when it was taken; see {@link RegionRuntime.readUsage}. */
+    this.usage = undefined
+    this.usageAt = 0
+  }
+
+  /**
+   * Resolve the current credential, exchanging a PAT when that is the source.
+   *
+   * The Qoder app owns the token's lifecycle and refreshes it in its own
+   * store, so an expired token is re-read from disk rather than cached — a
+   * user who reopened the app is picked up on the next request, with no
+   * restart. A PAT, by contrast, is exchanged once and then reused until its
+   * own expiry.
+   */
+  async resolveCredential() {
+    if (this.exchanged !== undefined) {
+      if (this.exchanged.source === 'env-pat' && this.exchanged.expiresAt > Date.now()) return this.exchanged
+      if (this.exchanged.source !== 'env-pat' && !this.exchanged.expired) return this.exchanged
+    }
+    const fromApp = loadCredential(this.region, process.env.APPDATA ?? '')
+    const credential = fromApp ?? loadEnvCredential(this.region)
+    this.credential = credential
+    if (credential === undefined) {
+      this.exchanged = undefined
+      return undefined
+    }
+    if (credential.source === 'env-pat') {
+      const exchanged = await exchangePat(this.region, credential.token)
+      this.exchanged = {
+        ...credential,
+        token: exchanged.token,
+        refreshToken: exchanged.refreshToken,
+        expiresAt: exchanged.expiresAt,
+      }
+      return this.exchanged
+    }
+    this.exchanged = credential
+    return credential
+  }
+
+  /** Refresh the model catalog from upstream, keeping the last good one on failure. */
+  async refreshCatalog(force = false) {
+    if (!force && this.catalog.fresh()) return
+    let credential
+    try {
+      credential = await this.resolveCredential()
+    } catch (error) {
+      this.logger?.warn?.(`dsh-connect-qoder: ${this.region.displayName} credential resolution failed`, error)
+      return
+    }
+    if (credential === undefined) return
+    try {
+      const raw = await fetchModels(this.region, credential)
+      const entries = raw.map(normalizeEntry)
+      if (entries.length > 0) {
+        this.catalog.replace(entries)
+        this.invalidate?.()
+      }
+    } catch (error) {
+      this.logger?.warn?.(`dsh-connect-qoder: ${this.region.displayName} catalog refresh failed`, error)
+    }
+  }
+
+  /** Look up the upstream key for a user-facing model id. */
+  upstreamKey(modelId) {
+    const found = this.catalog.current().find((entry) => entry.id === modelId)
+    return found?.key
+  }
+
+  /** The catalog entry behind a user-facing model id. */
+  entryFor(modelId) {
+    return this.catalog.current().find((entry) => entry.id === modelId)
+  }
+
+  /**
+   * Read the account's usage, with a short cache.
+   *
+   * The card is the only consumer and it can be expanded repeatedly, so a
+   * reading taken moments ago is reused; `force` is what the panel's refresh
+   * button asks for. A failure is never cached, so a transient upstream problem
+   * does not pin the panel to an error state.
+   */
+  async readUsage(force = false) {
+    if (!force && this.usage !== undefined && Date.now() - this.usageAt < USAGE_TTL_MS) {
+      return this.usage
+    }
+    const credential = await this.resolveCredential()
+    if (credential === undefined) return undefined
+    const usage = await fetchUsage(this.region, credential)
+    this.usage = usage
+    this.usageAt = Date.now()
+    return usage
+  }
+}
+
+/**
+ * Start one region's shim and catalog lifecycle.
+ *
+ * @param enabledIdsFor - `(regionId) => string[]`, the user's roster choice. The
+ *   shim needs it so `GET /v1/models` — the endpoint the picker's discovery
+ *   reads — narrows the catalog the same way the adapter does.
+ * @returns the runtime plus its shim, or `undefined` when the shim could not
+ *   listen (the region is then simply absent rather than fatal).
+ */
+async function startRegion(region, ctx, enabledIdsFor) {
+  const runtime = new RegionRuntime(region, ctx)
+
+  // A region is published only when it can actually answer. Registering a
+  // provider whose sign-in is missing or expired puts a dead route in the model
+  // picker: selecting it sends a request the gateway answers with 403, which
+  // the UI reports as "the provider rejected this request" — blaming the user's
+  // account for a channel this plugin should never have offered. Skipping the
+  // region leaves the other one working and the picker honest.
+  let credential
+  try {
+    credential = await runtime.resolveCredential()
+  } catch (error) {
+    ctx.logger.warn(
+      `dsh-connect-qoder: ${region.displayName} sign-in is unusable; region not registered`,
+      error,
+    )
+    return undefined
+  }
+  if (credential === undefined) {
+    ctx.logger.info(
+      `dsh-connect-qoder: ${region.displayName} has no local sign-in; region not registered`,
+    )
+    return undefined
+  }
+  if (credential.expired === true) {
+    ctx.logger.warn(
+      `dsh-connect-qoder: ${region.displayName} sign-in has expired; region not registered ` +
+        `(open the ${region.displayName} app to renew it, then restart DSH)`,
+    )
+    return undefined
+  }
+
+  const shim = createQoderShim({
+    region,
+    resolveCredential: () => runtime.resolveCredential(),
+    resolveModels: () => runtime.catalog.current(),
+    resolveUpstreamKey: (id) => runtime.upstreamKey(id),
+    resolveAlwaysThinking: (id) => runtime.entryFor(id)?.alwaysThinking === true,
+    // Read on every listing so curating the roster reaches the picker live.
+    resolveEnabledIds: () => enabledIdsFor(region.id),
+    logger: ctx.logger,
+  })
+  try {
+    await shim.ready
+  } catch (error) {
+    ctx.logger.error(`dsh-connect-qoder: ${region.displayName} loopback endpoint failed to start`, error)
+    return undefined
+  }
+  return { runtime, shim }
+}
+
+/**
+ * Register every Qoder region.
+ *
+ * All regions are published through one adapter and one registration pair:
+ * `registerAdapter` maps a set of providers onto a single adapter, so calling
+ * it once per region would leave only the last provider owned.
+ *
+ * Activation is best-effort by design: this plugin contributes optional model
+ * routes, and a failure to do so must never take the profile down with it. The
+ * whole body is therefore guarded, so a fault here degrades to "Qoder models
+ * are absent" rather than a profile that cannot boot.
+ *
+ * @param ctx - the plugin context, with `llm` injected.
+ * @param config - the resolved plugin configuration.
+ */
+export async function apply(ctx, config = {}) {
+  try {
+    await activate(ctx, config)
+  } catch (error) {
+    ctx.logger.error('dsh-connect-qoder: activation failed; Qoder models will be unavailable', error)
+  }
+}
+
+/** The real activation sequence, called under {@link apply}'s guard. */
+async function activate(ctx, config) {
+  // The context-window, image, and roster preferences are read through a mutable
+  // holder so the settings section can change them without re-registering the
+  // adapter; the adapter re-reads them every time it builds a model list, and the
+  // shim re-reads them on every listing. The resolved config is the initial value.
+  let preferences = { ...config }
+  let invalidateAdapter = () => {}
+
+  /** The models the user enabled for one region; empty means "no filter". */
+  const enabledIdsFor = (regionId) => {
+    const byRegion = preferences.enabledModelIds
+    if (byRegion === null || typeof byRegion !== 'object') return []
+    const list = byRegion[regionId]
+    return Array.isArray(list) ? list.filter((id) => typeof id === 'string' && id.length > 0) : []
+  }
+
+  const started = []
+  for (const region of REGIONS) {
+    const entry = await startRegion(region, ctx, enabledIdsFor)
+    if (entry !== undefined) started.push(entry)
+  }
+  if (started.length === 0) {
+    ctx.logger.warn('dsh-connect-qoder: no Qoder region could start')
+    return
+  }
+
+  const { adapter, invalidate } = createQoderAdapter({
+    regions: started.map(({ runtime, shim }) => ({
+      region: runtime.region,
+      shim,
+      catalog: () => runtime.catalog.current(),
+    })),
+    preferMaximumContext: () => preferences.useMaximumContextWindow === true,
+    imageModeFor: (modelId) => {
+      const overrides = preferences.imageOverrides
+      if (overrides === null || typeof overrides !== 'object') return 'auto'
+      const saved = overrides[modelId]
+      return saved === 'on' || saved === 'off' ? saved : 'auto'
+    },
+    enabledIdsFor,
+  })
+  invalidateAdapter = invalidate
+  for (const { runtime } of started) {
+    runtime.invalidate = () => {
+      invalidate()
+      ctx.emit('llm/adapters-updated')
+    }
+  }
+
+  let releaseAdapter
+  let releaseDirectory
+  try {
+    releaseAdapter = ctx.llm.registerAdapter(
+      started.map(({ runtime }) => runtime.region.id),
+      adapter,
+    )
+    releaseDirectory = ctx.llm.registerConfigurableProviders(
+      started.map(({ runtime }) => ({
+        provider: runtime.region.id,
+        displayName: runtime.region.displayName,
+        settingsNs: QODER_SETTINGS_NS,
+        settingsPath: [],
+        declared: false,
+      })),
+    )
+  } catch (error) {
+    releaseAdapter?.()
+    releaseDirectory?.()
+    for (const { shim } of started) shim.close()
+    ctx.logger.error('dsh-connect-qoder: provider registration failed', error)
+    return
+  }
+
+  ctx.effect(() => () => {
+    releaseAdapter?.()
+    releaseDirectory?.()
+    for (const { runtime, shim } of started) {
+      if (runtime.refreshTimer !== undefined) clearInterval(runtime.refreshTimer)
+      shim.close()
+    }
+  })
+
+  // Publish the settings section. Without this the namespace a provider
+  // directory entry points at would hold no schema, and no configuration
+  // surface could render a control for this route — context-window choice
+  // included. The section is optional: a host without a settings service still
+  // gets working models, just no configuration surface.
+  ctx.inject(['settings'], (settingsCtx) => {
+    try {
+      settingsCtx.settings.installSection(ctx, QODER_SETTINGS_NS, QODER_SECTION, config, {
+        setSource(source) {
+          preferences = { ...preferences, ...source() }
+        },
+        onChange() {
+          // The capabilities a model advertises changed, so the picker must
+          // rebuild — and so must any other reader of the model catalog.
+          invalidateAdapter()
+          ctx.emit('llm/adapters-updated')
+        },
+      })
+    } catch (error) {
+      ctx.logger.warn('dsh-connect-qoder: settings section unavailable', error)
+    }
+  })
+
+  // The settings card needs the live model roster to render one row per model,
+  // and it cannot read the host catalog directly. This route is the only path,
+  // so it is mounted on the optional webServer context and answers with the
+  // catalog the adapter already holds — metadata only, never a credential.
+  ctx.inject(['webServer'], (webCtx) => {
+    try {
+      webCtx.effect(() =>
+        webCtx.webServer.register({
+          kind: 'exact',
+          path: QODER_MODELS_PATH,
+          handler: async (req, res) => {
+            if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed' })
+            if (!loopbackRequest(req)) return sendJson(res, 403, { error: 'origin-not-trusted' })
+            // `refresh=1` re-reads the catalog from upstream. It matters because
+            // both the roster and the rates move on their own: Qoder adds and
+            // retires models, and an off-peak discount flips the effective price
+            // at 22:00 and 08:00 Asia/Shanghai. Without this the picker would
+            // keep showing whatever was true at process start.
+            const force = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('refresh') === '1'
+            if (force) {
+              for (const { runtime } of started) {
+                try {
+                  await runtime.refreshCatalog(true)
+                } catch (error) {
+                  // A refresh failure must not blank the card: the last good
+                  // catalog is still served below.
+                  ctx.logger.warn(
+                    `dsh-connect-qoder: ${runtime.region.displayName} catalog refresh failed`,
+                    error,
+                  )
+                }
+              }
+            }
+            const now = new Date()
+            const models = []
+            for (const { runtime } of started) {
+              for (const entry of runtime.catalog.current()) {
+                models.push({
+                  id: entry.id,
+                  name: entry.name,
+                  region: runtime.region.id,
+                  regionName: runtime.region.displayName,
+                  isVL: entry.isVL === true,
+                  // The raw catalog multiplier, kept for reference.
+                  priceFactor: Number(entry.priceFactor) || 0,
+                  // The multiplier that applies right now, with the off-peak
+                  // window resolved — this is what the picker appends to the name.
+                  effectiveRate: rateNow(entry, now),
+                  offPeakActive: offPeakActive(entry, now),
+                  ...(entry.promotion !== undefined
+                    ? {
+                        promotion: {
+                          badge: entry.promotion.badge,
+                          description: entry.promotion.description,
+                          windowStart: entry.promotion.windowStart,
+                          windowEnd: entry.promotion.windowEnd,
+                          discountFactor: entry.promotion.discountFactor,
+                          beforePromotionPriceFactor: entry.promotion.beforePromotionPriceFactor,
+                          remainingSeconds: offPeakRemaining(entry, now),
+                        },
+                      }
+                    : {}),
+                })
+              }
+            }
+            const overrides = preferences.imageOverrides
+            const enabled = preferences.enabledModelIds
+            sendJson(res, 200, {
+              models,
+              imageOverrides: overrides !== null && typeof overrides === 'object' ? overrides : {},
+              useMaximumContextWindow: preferences.useMaximumContextWindow === true,
+              enabledModelIds: enabled !== null && typeof enabled === 'object' ? enabled : {},
+              refreshedAt: Date.now(),
+            })
+          },
+        }),
+      )
+    } catch (error) {
+      ctx.logger.warn('dsh-connect-qoder: model route unavailable', error)
+    }
+  })
+
+  // The usage panel needs the same treatment: the quota lives upstream behind a
+  // bearer token the browser must never hold, so the host reads it and hands the
+  // card a credential-free summary. Each region is read independently and a
+  // failing region is reported as unavailable rather than failing the panel, so
+  // one dead sign-in cannot hide the other region's numbers.
+  ctx.inject(['webServer'], (webCtx) => {
+    try {
+      webCtx.effect(() =>
+        webCtx.webServer.register({
+          kind: 'exact',
+          path: QODER_USAGE_PATH,
+          handler: async (req, res) => {
+            if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed' })
+            if (!loopbackRequest(req)) return sendJson(res, 403, { error: 'origin-not-trusted' })
+            const force = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('refresh') === '1'
+            const regions = await Promise.all(
+              started.map(async ({ runtime }) => {
+                const base = {
+                  region: runtime.region.id,
+                  regionName: runtime.region.displayName,
+                  manageUrl: runtime.region.manageUrl,
+                }
+                try {
+                  const usage = await runtime.readUsage(force)
+                  return usage === undefined ? { ...base, available: false } : { ...base, available: true, ...usage }
+                } catch (error) {
+                  ctx.logger.warn(
+                    `dsh-connect-qoder: ${runtime.region.displayName} usage read failed`,
+                    error,
+                  )
+                  return { ...base, available: false }
+                }
+              }),
+            )
+            sendJson(res, 200, { regions })
+          },
+        }),
+      )
+    } catch (error) {
+      ctx.logger.warn('dsh-connect-qoder: usage route unavailable', error)
+    }
+  })
+
+  // Load credentials and catalogs without blocking activation: the providers
+  // are registered either way, and an empty catalog is how DSH hides a model
+  // group until a sign-in appears.
+  for (const { runtime } of started) {
+    void runtime.refreshCatalog(true).then(() => {
+      runtime.refreshTimer = setInterval(() => {
+        void runtime.refreshCatalog(true)
+      }, CATALOG_TTL_MS)
+      runtime.refreshTimer.unref?.()
+    })
+  }
+}