dsh-cline-pass 0.1.0

package/lib/cline.js

@@ -0,0 +1,194 @@
+/**
+ * Transport for the Cline gateway and its public catalogs. Transport only: no
+ * pinning, retry, or failover policy lives here (see `adapter.js`).
+ *
+ * - `POST {baseURL}/chat/completions` — the gateway
+ * - `GET  {baseURL}/models` — the gateway's own catalog
+ * - `GET  api.cline.bot/.../recommended-models` — official subscription list
+ * - `GET  models.dev/api.json` — community registry, a backstop
+ * - `GET  openrouter.ai/api/v1/...` — endpoint detail for direct-pipeline models
+ *
+ * @module dsh-cline-pass/cline
+ */
+/** The public Cline endpoint that lists subscription models without auth. */
+export const RECOMMENDED_MODELS_URL = 'https://api.cline.bot/api/v1/ai/cline/recommended-models'
+/** The community model registry. */
+export const MODELS_DEV_URL = 'https://models.dev/api.json'
+/** OpenRouter's public API, used only for direct-pipeline endpoint detail. */
+export const OPENROUTER_API = 'https://openrouter.ai/api/v1'
+
+/** Combine a caller signal with a timeout signal. */
+function withTimeout(signal, timeoutMs) {
+  const signals = []
+  if (Number.isFinite(timeoutMs) && timeoutMs > 0) signals.push(AbortSignal.timeout(timeoutMs))
+  if (signal !== undefined && signal !== null) signals.push(signal)
+  if (signals.length === 0) return undefined
+  return signals.length === 1 ? signals[0] : AbortSignal.any(signals)
+}
+
+/** Strip a trailing slash so paths can be appended literally. */
+export function trimBase(baseURL) {
+  return String(baseURL ?? '').trim().replace(/\/+$/, '')
+}
+
+/**
+ * The gateway's own chat-completions endpoint for one base URL.
+ * @param baseURL - e.g. `https://api.cline.bot/api/v1`.
+ */
+export function chatURL(baseURL) {
+  return `${trimBase(baseURL)}/chat/completions`
+}
+
+/**
+ * Send one JSON request and decode whatever comes back.
+ * @returns `{ status, ok, json, text }`; never throws for an HTTP error status.
+ */
+export async function sendJSON(url, { method = 'GET', apiKey = '', body, signal, timeoutMs = 60000, headers = {} } = {}) {
+  const outgoing = {
+    method,
+    headers: {
+      Accept: 'application/json',
+      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      ...(apiKey === '' ? {} : { Authorization: `Bearer ${apiKey}` }),
+      ...headers,
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    signal: withTimeout(signal, timeoutMs),
+  }
+  const response = await fetch(url, outgoing)
+  const text = await response.text()
+  let json = null
+  if (text.length > 0) {
+    try {
+      json = JSON.parse(text)
+    } catch {
+      json = null
+    }
+  }
+  return { status: response.status, ok: response.ok, json, text }
+}
+
+/**
+ * Send one chat completion, non-streaming.
+ * @returns `{ status, ok, json, text }` with the gateway envelope already unwrapped by the caller.
+ */
+export function chatCompletion(options) {
+  const { baseURL, apiKey, body, signal, timeoutMs = 180000 } = options
+  return sendJSON(chatURL(baseURL), { method: 'POST', apiKey, body, signal, timeoutMs })
+}
+
+/**
+ * Open a streaming chat completion and hand back the live response.
+ * @returns the raw `fetch` Response so the caller owns SSE iteration and abort.
+ */
+export async function openChatStream({ baseURL, apiKey, body, signal, headers = {} }) {
+  return await fetch(chatURL(baseURL), {
+    method: 'POST',
+    headers: {
+      Accept: 'text/event-stream',
+      'Content-Type': 'application/json',
+      ...(apiKey === '' ? {} : { Authorization: `Bearer ${apiKey}` }),
+      ...headers,
+    },
+    body: JSON.stringify(body),
+    signal,
+  })
+}
+
+/**
+ * List the gateway's own catalog ids.
+ * @returns the model ids; an empty array when the call fails or returns nothing.
+ */
+export async function fetchGatewayCatalog({ baseURL, apiKey, signal, timeoutMs = 30000 }) {
+  try {
+    const result = await sendJSON(`${trimBase(baseURL)}/models`, { apiKey, signal, timeoutMs })
+    const ids = (result.json?.data ?? []).map((model) => model?.id).filter((id) => typeof id === 'string')
+    return ids
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Collect `cline-pass/*` ids from the official endpoints and the community registry.
+ *
+ * Additive by design: every source that answers contributes, and a source that
+ * fails is skipped rather than failing the scan.
+ *
+ * @returns `{ models, sources }` — deduplicated ids plus the sources that answered.
+ */
+export async function fetchOfficialModels({ signal, timeoutMs = 30000, fetchImpl = fetch } = {}) {
+  const found = new Set()
+  const sources = []
+  const add = (value) => {
+    const id = typeof value === 'string' ? value : value?.id
+    if (typeof id !== 'string') return
+    const normalized = id.trim().toLowerCase()
+    if (normalized.startsWith('cline-pass/')) found.add(normalized)
+  }
+  try {
+    const response = await fetchImpl(RECOMMENDED_MODELS_URL, { signal: withTimeout(signal, timeoutMs) })
+    if (response.ok) {
+      const json = await response.json()
+      const list = json?.clinePass ?? json?.data?.clinePass
+      if (Array.isArray(list) && list.length > 0) {
+        list.forEach(add)
+        sources.push('cline.api')
+      }
+    }
+  } catch { /* source unavailable */ }
+  try {
+    const response = await fetchImpl(MODELS_DEV_URL, { signal: withTimeout(signal, timeoutMs) })
+    if (response.ok) {
+      const json = await response.json()
+      const provider = json?.providers?.['cline-pass'] ?? json?.['cline-pass']
+      if (provider?.models !== undefined && provider.models !== null) {
+        Object.keys(provider.models).forEach((id) => add(id.startsWith('cline-pass/') ? id : `cline-pass/${id}`))
+        sources.push('models.dev')
+      }
+    }
+  } catch { /* source unavailable */ }
+  return { models: [...found].filter((id) => /^cline-pass\/[a-z0-9._-]+$/.test(id)), sources }
+}
+
+/**
+ * Resolve a canonical slug against OpenRouter's public catalog, tolerating the
+ * hyphen differences between the gateway's slug and OpenRouter's id.
+ * @returns the real OpenRouter id, or null.
+ */
+export async function resolveOpenRouterSlug(slug, { signal, timeoutMs = 30000 } = {}) {
+  try {
+    const result = await sendJSON(`${OPENROUTER_API}/models`, { signal, timeoutMs })
+    const ids = (result.json?.data ?? []).map((model) => model?.id).filter((id) => typeof id === 'string')
+    const normalize = (value) => String(value).toLowerCase().replace(/[^a-z0-9]/g, '')
+    return ids.find((id) => id === slug) ?? ids.find((id) => normalize(id) === normalize(slug)) ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Per-upstream endpoint detail (context length, recent uptime) for one
+ * OpenRouter model. Only meaningful for direct-pipeline models.
+ * @returns `{ slug, endpoints }`, where endpoints is `[{ slug, name, endpoints, context, uptime }]`.
+ */
+export async function openRouterEndpoints(slug, { signal, timeoutMs = 30000 } = {}) {
+  const real = await resolveOpenRouterSlug(slug, { signal, timeoutMs })
+  if (real === null) return { slug, endpoints: [] }
+  try {
+    const result = await sendJSON(`${OPENROUTER_API}/models/${real}/endpoints`, { signal, timeoutMs })
+    const detail = new Map()
+    for (const entry of result.json?.data?.endpoints ?? []) {
+      const providerSlug = String(entry?.tag ?? '').split('/')[0] || String(entry?.provider_name ?? '').toLowerCase().replace(/\s+/g, '-')
+      if (providerSlug === '') continue
+      const current = detail.get(providerSlug) ?? { slug: providerSlug, name: String(entry?.provider_name ?? providerSlug), endpoints: 0, context: 0, uptime: 0 }
+      current.endpoints += 1
+      current.context = Math.max(current.context, Number(entry?.context_length ?? 0))
+      current.uptime = Math.max(current.uptime, Math.round(Number(entry?.uptime_last_30m ?? 0)))
+      detail.set(providerSlug, current)
+    }
+    return { slug: real, endpoints: [...detail.values()] }
+  } catch {
+    return { slug: real, endpoints: [] }
+  }
+}

package/lib/engine.js

@@ -0,0 +1,405 @@
+/**
+ * The engine: account selection, pinned request chains with failover, probing,
+ * validation, and request recording. It owns every network call, so the adapter
+ * and the management tools apply identical pinning semantics.
+ *
+ * Failover contract: a candidate is abandoned only while nothing has been
+ * delivered yet. A non-2xx, a transport failure, or an error payload before the
+ * first content delta moves to the next candidate; once a chunk has been
+ * produced the stream is the answer, and a later failure is reported as such.
+ *
+ * @module dsh-cline-pass/engine
+ */
+import { LlmError } from '@deepseek-ai/dsh-llm'
+import {
+  chatCompletion,
+  fetchGatewayCatalog,
+  fetchOfficialModels,
+  openChatStream,
+  openRouterEndpoints,
+} from './cline.js'
+import {
+  buildAttempts,
+  classifyUpstreamError,
+  errorText,
+  extractAvailableProviders,
+  injectPrefs,
+  mergeUpstreams,
+  parseRouting,
+  parseTier0,
+  unwrapEnvelope,
+} from './protocol.js'
+
+/** How many upstreams are validated concurrently. */
+const VALIDATE_CONCURRENCY = 5
+
+/**
+ * Parse an SSE body into decoded JSON frames.
+ * @param body - a web ReadableStream of UTF-8 bytes.
+ * @returns every `data:` payload up to `[DONE]`.
+ */
+export async function* parseServerSentEvents(body) {
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for await (const bytes of body) {
+    buffer += decoder.decode(bytes, { stream: true })
+    let index = buffer.indexOf('\n')
+    while (index >= 0) {
+      const line = buffer.slice(0, index).replace(/\r$/, '')
+      buffer = buffer.slice(index + 1)
+      index = buffer.indexOf('\n')
+      if (line.length === 0 || line.startsWith(':')) continue
+      if (!line.startsWith('data:')) continue
+      const payload = line.slice(5).trim()
+      if (payload === '[DONE]') {
+        yield '[DONE]'
+        return
+      }
+      try {
+        yield JSON.parse(payload)
+      } catch { /* an unparseable frame carries nothing to deliver */ }
+    }
+  }
+  const tail = buffer.trim()
+  if (tail.startsWith('data:')) {
+    const payload = tail.slice(5).trim()
+    if (payload === '[DONE]') {
+      yield '[DONE]'
+      return
+    }
+    if (payload.length > 0) {
+      try {
+        yield JSON.parse(payload)
+      } catch { /* see above */ }
+    }
+  }
+  throw new LlmError('stream ended without [DONE]', 'STREAM_CLOSED')
+}
+
+/**
+ * Create the engine.
+ *
+ * @param options.resolveAccount - async `() => { name, key, baseURL }`; called
+ *   once per attempt, so round-robin pools rotate per attempt.
+ * @param options.store - the observation store (probe results, history).
+ * @param options.logger - optional Cordis logger.
+ * @param options.attemptTimeoutMs - per-attempt budget for a chat request.
+ * @param options.probeTimeoutMs - budget for probe/validate requests.
+ */
+export function createEngine({
+  resolveAccount,
+  store,
+  logger,
+  attemptTimeoutMs = 180000,
+  probeTimeoutMs = 60000,
+}) {
+  /**
+   * One pinned request, non-streaming.
+   * @returns `{ status, ok, json, text, routing, attempt, account }`.
+   */
+  async function attemptChat(model, body, attempt, { signal, timeoutMs = attemptTimeoutMs } = {}) {
+    const account = await resolveAccount()
+    const pinned = injectPrefs(body, store.metaOf(model), attempt)
+    const started = Date.now()
+    const result = await chatCompletion({
+      baseURL: account.baseURL,
+      apiKey: account.key,
+      body: pinned,
+      signal,
+      timeoutMs,
+    })
+    const payload = unwrapEnvelope(result.json)
+    const failed = result.ok !== true || (payload?.error !== undefined && payload?.choices === undefined)
+    return {
+      attempt,
+      account,
+      status: failed ? (payload?.error === undefined ? result.status : 502) : 200,
+      ok: !failed,
+      json: payload,
+      text: result.text,
+      ms: Date.now() - started,
+      routing: failed ? {} : parseRouting(payload),
+      error: failed ? (errorText(payload?.error) || result.text.slice(0, 400) || `HTTP ${result.status}`) : '',
+    }
+  }
+
+  /**
+   * Run one model's ordered candidate chain until an attempt succeeds.
+   * @returns `{ ok, result?, trace, error }` — `result` is the winning attempt.
+   */
+  async function runChain(model, body, pinConfig, { signal, timeoutMs } = {}) {
+    const trace = []
+    let last = null
+    for (const attempt of buildAttempts(pinConfig)) {
+      const outcome = await attemptChat(model, body, attempt, { signal, timeoutMs })
+      trace.push({ upstream: attempt.upstream ?? '(auto)', status: outcome.status, ms: outcome.ms, note: outcome.error === '' ? 'ok' : outcome.error.slice(0, 160) })
+      last = outcome
+      if (outcome.ok) return { ok: true, result: outcome, trace, error: '' }
+      // A channel that refuses a strict pin is learned as unusable for it.
+      if (attempt.upstream !== null && outcome.error !== '') store.learnUpstream(model, attempt.upstream, classifyUpstreamError(outcome.error), outcome.error, outcome.ms)
+      if (attempt.upstream === null && (attempt.excludeList ?? []).length > 0 && outcome.error !== '') learnFromError(model, outcome.error)
+    }
+    return { ok: false, result: last, trace, error: last?.error ?? 'no candidate succeeded' }
+  }
+
+  /** Merge a gateway error's own provider list into the model's channel list. */
+  function learnFromError(model, message) {
+    const match = /Available providers are:\s*([^.]+)/.exec(String(message ?? ''))
+    if (match === null) return
+    const tokens = match[1].split(/,\s*/).map((token) => token.trim()).filter((token) => /^[a-z0-9][a-z0-9-]*$/.test(token))
+    if (tokens.length === 0) return
+    const meta = store.metaOf(model)
+    const merged = mergeUpstreams(meta.upstreams ?? [], tokens)
+    if (merged.length !== (meta.upstreams ?? []).length) store.learn(model, { upstreams: merged })
+  }
+
+  /**
+   * Probe one model: detect its pipeline, read back the upstream it used, and
+   * harvest the precise channel list for that pipeline. Costs one tiny request.
+   */
+  async function probe(model, { signal, timeoutMs = attemptTimeoutMs } = {}) {
+    const account = await resolveAccount()
+    const started = Date.now()
+    const result = await chatCompletion({
+      baseURL: account.baseURL,
+      apiKey: account.key,
+      body: { model, messages: [{ role: 'user', content: 'Reply with the word OK' }], max_tokens: 256 },
+      signal,
+      timeoutMs,
+    })
+    const payload = unwrapEnvelope(result.json)
+    const ms = Date.now() - started
+    if (payload?.error !== undefined && payload?.choices === undefined) {
+      const message = errorText(payload.error)
+      store.learn(model, { ok: false, lastError: message, lastMs: ms })
+      return { ok: false, ms, model, error: message }
+    }
+    const routing = parseRouting(payload)
+    const pipeline = routing.pipeline
+    let harvested = null
+    if (pipeline !== null) harvested = await harvest(model, pipeline, account, { signal, timeoutMs: probeTimeoutMs })
+    let endpoints = []
+    let openrouterSlug = null
+    if (pipeline !== 'planner' && typeof routing.canonicalSlug === 'string') {
+      const detail = await openRouterEndpoints(routing.canonicalSlug, { signal, timeoutMs: probeTimeoutMs })
+      endpoints = detail.endpoints
+      openrouterSlug = detail.slug
+    }
+    const previous = store.metaOf(model)
+    const upstreamDetail = { ...(previous.upstreamDetail ?? {}) }
+    for (const entry of endpoints) upstreamDetail[entry.slug] = entry
+    const upstreams = pipeline === 'planner'
+      ? mergeUpstreams(harvested, routing.fallbacks)
+      : mergeUpstreams(routing.fallbacks, harvested, Object.keys(upstreamDetail))
+    const tier0 = [...new Set([...(previous.tier0 ?? []), ...parseTier0(routing.plan)])]
+    const meta = store.learn(model, {
+      ok: true,
+      pipeline,
+      pinnable: pipeline !== null,
+      availableProviders: harvested ?? previous.availableProviders ?? [],
+      canonicalSlug: routing.canonicalSlug ?? previous.canonicalSlug ?? null,
+      openrouterSlug: openrouterSlug ?? previous.openrouterSlug ?? null,
+      upstreamDetail,
+      upstreams,
+      tier0,
+      lastProvider: routing.finalProvider ?? previous.lastProvider ?? null,
+      lastMs: ms,
+      probedAt: Date.now(),
+      lastError: '',
+    })
+    return {
+      ok: true,
+      ms,
+      model,
+      error: '',
+      pipeline: meta.pipeline,
+      pinnable: meta.pinnable === true,
+      canonicalSlug: meta.canonicalSlug ?? '',
+      lastProvider: meta.lastProvider ?? '',
+      upstreams: meta.upstreams ?? [],
+      availableProviders: meta.availableProviders ?? [],
+      tier0: meta.tier0 ?? [],
+    }
+  }
+
+  /**
+   * Harvest the exact channel list for one pipeline by pinning a channel that
+   * cannot exist: the router fails before spending a token and names every
+   * provider it could have used.
+   */
+  async function harvest(model, pipeline, account, { signal, timeoutMs = probeTimeoutMs } = {}) {
+    const base = { model, messages: [{ role: 'user', content: 'hi' }], max_tokens: 16 }
+    const body = pipeline === 'planner'
+      ? { ...base, providerOptions: { gateway: { only: ['__probe__'] } } }
+      : { ...base, provider: { only: ['__probe__'] } }
+    try {
+      const result = await chatCompletion({ baseURL: account.baseURL, apiKey: account.key, body, signal, timeoutMs })
+      const payload = unwrapEnvelope(result.json)
+      const message = errorText(payload?.error) || result.text
+      return extractAvailableProviders(message, pipeline)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Test every known channel of a model once and record the verdicts.
+   * @returns `{ results: [{ upstream, status, ms, note }], summary }`.
+   */
+  async function validate(model, { signal, timeoutMs = probeTimeoutMs } = {}) {
+    const meta = store.metaOf(model)
+    const list = Array.isArray(meta.upstreams) ? meta.upstreams : []
+    const pipeline = meta.pipeline ?? null
+    const results = []
+    for (let index = 0; index < list.length; index += VALIDATE_CONCURRENCY) {
+      const batch = list.slice(index, index + VALIDATE_CONCURRENCY)
+      const settled = await Promise.all(batch.map(async (upstream) => {
+        const started = Date.now()
+        const base = { model, messages: [{ role: 'user', content: 'hi' }], max_tokens: 16 }
+        const body = pipeline === 'planner'
+          ? { ...base, providerOptions: { gateway: { only: [upstream] } } }
+          : { ...base, provider: { only: [upstream] } }
+        try {
+          const account = await resolveAccount()
+          const result = await chatCompletion({ baseURL: account.baseURL, apiKey: account.key, body, signal, timeoutMs })
+          const payload = unwrapEnvelope(result.json)
+          const ms = Date.now() - started
+          let status = 'unknown'
+          let note = ''
+          if (payload?.error !== undefined && payload?.choices === undefined) {
+            note = errorText(payload.error)
+            status = classifyUpstreamError(note)
+          } else if (payload?.choices !== undefined) {
+            status = 'ok'
+          }
+          return { upstream, status, ms, note: note.slice(0, 160) }
+        } catch (error) {
+          return { upstream, status: 'unknown', ms: Date.now() - started, note: errorText(error).slice(0, 160) }
+        }
+      }))
+      for (const result of settled) {
+        store.learnUpstream(model, result.upstream, result.status, result.note, result.ms)
+        results.push(result)
+      }
+    }
+    const summary = { ok: 0, limited: 0, bad: 0, auth: 0, unknown: 0 }
+    for (const result of results) summary[result.status] = (summary[result.status] ?? 0) + 1
+    store.learn(model, { validatedAt: Date.now() })
+    return { results, summary }
+  }
+
+  /**
+   * Send one small chat through a (possibly temporary) pin configuration and
+   * report what served it. Nothing is persisted.
+   */
+  async function test(model, { upstreams, exclude, signal } = {}) {
+    const pin = currentPin(model, { upstreams, exclude })
+    const started = Date.now()
+    const outcome = await runChain(model, { model, messages: [{ role: 'user', content: 'Reply with the word OK' }], max_tokens: 256 }, pin, { signal, timeoutMs: attemptTimeoutMs })
+    const ms = Date.now() - started
+    if (!outcome.ok) {
+      record(model, { provider: null, attempts: outcome.trace.map((row) => row.upstream), ms, stream: false, error: outcome.error, account: outcome.result?.account?.name ?? null })
+      return { ok: false, ms, model, error: outcome.error, targets: pin.upstreams ?? [], excluded: pin.exclude ?? [], trace: outcome.trace, actual: '', content: '', account: outcome.result?.account?.name ?? '' }
+    }
+    const routing = outcome.result.routing
+    record(model, { provider: routing.finalProvider, canonical: routing.canonicalSlug, attempts: outcome.trace.map((row) => row.upstream), ms, stream: false, error: null, account: outcome.result.account?.name ?? null })
+    return {
+      ok: true,
+      ms,
+      model,
+      error: '',
+      targets: pin.upstreams ?? [],
+      excluded: pin.exclude ?? [],
+      trace: outcome.trace,
+      actual: routing.finalProvider ?? '',
+      actualName: routing.finalProviderName ?? '',
+      pipeline: routing.pipeline ?? '',
+      pinnable: routing.pipeline !== null,
+      canonicalSlug: routing.canonicalSlug ?? '',
+      account: outcome.result.account?.name ?? '',
+      content: String(routing.content ?? '').slice(0, 120),
+    }
+  }
+
+  /**
+   * Check one account key against the gateway with a single small request.
+   *
+   * A key that authenticates but whose model still errors (a reasoning model
+   * burning `max_tokens` into an empty completion, for example) counts as
+   * authorized: only a real authentication failure is reported as one.
+   */
+  async function testAccount({ key, baseURL, model, signal, timeoutMs = probeTimeoutMs }) {
+    const started = Date.now()
+    try {
+      const result = await chatCompletion({
+        baseURL,
+        apiKey: key,
+        body: { model, messages: [{ role: 'user', content: 'Say OK' }], max_tokens: 512 },
+        signal,
+        timeoutMs,
+      })
+      const payload = unwrapEnvelope(result.json)
+      const ms = Date.now() - started
+      if (payload?.error !== undefined && payload?.choices === undefined) {
+        const message = errorText(payload.error)
+        const authFailed = /unauthorized|re-authenticate|invalid\s*api|401/i.test(message)
+        return { ok: !authFailed, authorized: !authFailed, ms, model, error: message }
+      }
+      return { ok: true, authorized: true, ms, model, error: '' }
+    } catch (error) {
+      return { ok: false, authorized: false, ms: Date.now() - started, model, error: errorText(error) }
+    }
+  }
+
+  /** Resolve a per-call pin override against the stored configuration. */
+  function currentPin(model, override = {}) {
+    const stored = pinOf(model)
+    return {
+      upstreams: Array.isArray(override.upstreams) ? override.upstreams.map(String) : stored.upstreams,
+      exclude: Array.isArray(override.exclude) ? override.exclude.map(String) : stored.exclude,
+      pinMode: stored.pinMode,
+      sort: stored.sort,
+    }
+  }
+
+  /** The configured pin for one model, read through the plugin's live config. */
+  let pinReader = () => ({ upstreams: [], exclude: [], pinMode: 'strict', sort: null })
+  const pinOf = (model) => pinReader(model)
+
+  /** Record one request in the observation store. */
+  function record(model, info) {
+    store.record({ model, ...info })
+  }
+
+  return {
+    /** Replace the function that reads a model's configured pin. */
+    setPinReader(reader) {
+      pinReader = reader
+    },
+    /** Refresh the gateway's own catalog ids. */
+    async gatewayCatalog(options = {}) {
+      const account = await resolveAccount()
+      return await fetchGatewayCatalog({ baseURL: account.baseURL, apiKey: account.key, ...options })
+    },
+    /** Refresh the official subscription model list. */
+    async officialModels(options = {}) {
+      return await fetchOfficialModels(options)
+    },
+    /** The resolved account for the next request (round-robin aware). */
+    resolveAccount,
+    attemptChat,
+    runChain,
+    probe,
+    validate,
+    test,
+    testAccount,
+    currentPin,
+    record,
+    learnFromError,
+    chatCompletion,
+    openChatStream,
+    parseServerSentEvents,
+    buildAttempts,
+    injectPrefs,
+  }
+}