@lihuu/dsh-ollama-cloud 0.1.2 → 0.2.0

package/src/discovery.ts

@@ -0,0 +1,252 @@
+/**
+ * Answering "which models can this draft serve?" for the Models settings
+ * page's fetch action.
+ *
+ * A draft naming this plugin's route is answered **from the adapter's own
+ * catalog**, with no network call: the resolved section is the authoritative
+ * list for the route, and it carries the cloud-suffixed ids requests actually
+ * use. Only a draft carrying an endpoint — a gateway or OpenAI-compatible
+ * mirror the catalog says nothing about — is interrogated over the wire at
+ * `GET {baseURL}/models`, the one listing shape such endpoints agree on.
+ *
+ * Nothing here is stored: the request carries a draft the user is still
+ * editing, and the reply is candidate metadata the surface offers for
+ * adoption. The section remains the only thing that decides what the route
+ * serves.
+ *
+ * @module llm-ollama-cloud/discovery
+ */
+
+import { INVALID_CREDENTIAL_CODE, LlmError, normalizeApiKey } from '@deepseek-ai/dsh-llm'
+import type { LlmDiscoveredModel, LlmModelDiscoveryOperation } from '@deepseek-ai/dsh-llm'
+import { attributionHeaders } from '@deepseek-ai/dsh-llm'
+import type { OllamaCatalogModel } from './adapter.ts'
+
+/**
+ * Endpoint replies larger than this are refused. The endpoint is whatever URL
+ * the user typed, so the ceiling holds on the bytes actually read rather than
+ * on the length the server claims.
+ */
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+/** One entry of an OpenAI-compatible `GET /models` reply. */
+interface ListingEntry {
+  id?: unknown
+  /** Common gateway extensions; absent from the official listing. */
+  name?: unknown
+  display_name?: unknown
+  context_window?: unknown
+  context_length?: unknown
+  max_tokens?: unknown
+  max_output_tokens?: unknown
+}
+
+/** A positive integer field of a listing entry, or `undefined` when absent or unusable. */
+function capacity(...candidates: readonly unknown[]): number | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'number' && Number.isInteger(candidate) && candidate > 0) return candidate
+  }
+  return undefined
+}
+
+/** A non-empty string field of a listing entry, or `undefined`. */
+function label(...candidates: readonly unknown[]): string | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.length > 0) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Join the endpoint base with the listing path. The base is treated as a
+ * prefix rather than a URL to resolve against, so a deployment path such as
+ * `https://gateway.example/openai/v1` keeps its segments instead of losing
+ * them to `URL` resolution.
+ */
+function listingUrl(baseURL: string): string {
+  return `${baseURL.replace(/\/+$/, '')}/models`
+}
+
+/**
+ * Accept one probe key, or refuse it before the header is built. Without this
+ * the `fetch` below would throw a ByteString `TypeError` that the transport
+ * catch reports as `could not reach <url>` — blaming the network for a local,
+ * deterministic fault.
+ * @param raw - the key typed into the form or read from storage.
+ * @returns the trimmed, usable key.
+ */
+function usableProbeKey(raw: string): string {
+  const checked = normalizeApiKey(raw)
+  if (checked.ok) return checked.value
+  throw new LlmError(
+    checked.reason === 'empty'
+      ? 'this provider\'s API key is blank; enter it on the Models page, or clear it to probe unauthenticated'
+      : 'this provider\'s API key contains characters no HTTP header can carry; paste the raw key only',
+    INVALID_CREDENTIAL_CODE,
+  )
+}
+
+/**
+ * Read a reply body, refusing one that outgrows the ceiling. A declared length
+ * is checked first so an honest server is turned away without transferring
+ * anything; the accumulated total is what actually enforces the bound, because
+ * a server that under-declares (or streams) tells us nothing up front.
+ */
+async function readBounded(response: Response, url: string): Promise<string> {
+  const oversized = (): LlmError =>
+    new LlmError(`${url} answered with more than ${MAX_RESPONSE_BYTES} bytes`, 'DISCOVERY_FAILED')
+  const declared = Number(response.headers.get('content-length') ?? Number.NaN)
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel()
+    throw oversized()
+  }
+  if (response.body === null) return ''
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > MAX_RESPONSE_BYTES) throw oversized()
+      chunks.push(value)
+    }
+  } finally {
+    /* v8 ignore next 4 -- cancel() after a completed or abandoned read settles without rejecting; unobserved best-effort cleanup. */
+    await reader.cancel().catch(() => {
+      // Cancel after a drained read, or after this function walked away from
+      // an oversized one, is cleanup; the reply is already decided either way.
+    })
+  }
+  const body = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(body)
+}
+
+/**
+ * Read one OpenAI-compatible listing reply. Entries without a usable id are
+ * skipped rather than failing the whole interrogation: a single malformed row
+ * should not deny the user the rest of a working endpoint's catalog.
+ */
+function readListing(body: unknown): LlmDiscoveredModel[] {
+  const data = (body as { data?: unknown } | null)?.data
+  if (!Array.isArray(data)) {
+    throw new LlmError(
+      'the endpoint\'s model listing has no "data" array; enter this provider\'s models by hand',
+      'DISCOVERY_FAILED',
+    )
+  }
+  const models: LlmDiscoveredModel[] = []
+  for (const raw of data) {
+    const entry = raw as ListingEntry | null
+    const id = label(entry?.id)
+    if (id === undefined) continue
+    const name = label(entry?.name, entry?.display_name)
+    const contextWindow = capacity(entry?.context_window, entry?.context_length)
+    const maxTokens = capacity(entry?.max_output_tokens, entry?.max_tokens)
+    models.push({
+      id,
+      ...name === undefined ? {} : { name },
+      ...contextWindow === undefined ? {} : { contextWindow },
+      ...maxTokens === undefined ? {} : { maxTokens },
+    })
+  }
+  return models
+}
+
+/**
+ * Interrogate one draft provider for the models it advertises.
+ * @param request - the endpoint and one-shot credential to use.
+ * @param installed - the route's own catalog as currently resolved; the
+ *   answer for a draft naming the route.
+ * @param storedApiKey - the credential the stored section resolves, asked for
+ *   only when the draft carries none and only on the path that reaches the
+ *   network. A configuration surface never holds a stored secret — it edits a
+ *   redacted descriptor — so without this an already-configured route would be
+ *   interrogated unauthenticated and answer 401.
+ * @returns the advertised models in endpoint order.
+ * @throws LlmError when the draft names neither a catalog route nor an
+ *   endpoint, the endpoint refuses or fails the request, or the reply is not
+ *   a model listing.
+ */
+export async function discoverModels(
+  request: LlmModelDiscoveryOperation,
+  installed: readonly OllamaCatalogModel[],
+  storedApiKey?: () => Promise<string | undefined>,
+): Promise<readonly LlmDiscoveredModel[]> {
+  // A named route already has its answer, and a better one: the installed
+  // entries carry the cloud-suffixed ids and capacities no listing endpoint
+  // reports, and they are already normalized through the same step the
+  // adapter's own requests go through.
+  if (request.provider !== undefined && installed.length > 0) {
+    return installed.map(model => ({
+      id: model.id,
+      name: model.name ?? model.id,
+      ...model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow },
+      ...model.maxTokens === undefined ? {} : { maxTokens: model.maxTokens },
+    }))
+  }
+  if (request.baseURL === undefined || request.baseURL.length === 0) {
+    throw new LlmError(
+      'model discovery needs a baseURL to interrogate; set one, or enter this provider\'s models by hand',
+      'DISCOVERY_FAILED',
+    )
+  }
+  const url = listingUrl(request.baseURL)
+  // A key typed into the form wins: it is the one the user is testing, and it
+  // may be the replacement for exactly the stored key that is failing. The
+  // stored one is only asked for here, past the catalog short-circuit, so a
+  // route answered from the registry costs no credential lookup — and no
+  // diagnostic about a credential it never needed. A probe carrying no key
+  // stays unauthenticated, which is how an auth-free gateway is meant to be
+  // asked.
+  const supplied = request.apiKey ?? await storedApiKey?.()
+  const apiKey = supplied === undefined ? undefined : usableProbeKey(supplied)
+  let response: Response
+  try {
+    response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        accept: 'application/json',
+        ...apiKey === undefined ? {} : { authorization: `Bearer ${apiKey}` },
+        ...attributionHeaders(),
+      },
+      ...request.signal === undefined ? {} : { signal: request.signal },
+    })
+  } catch (error: unknown) {
+    if (request.signal?.aborted) {
+      throw new LlmError('model discovery aborted by caller', 'ABORTED', { cause: error })
+    }
+    throw new LlmError(`could not reach ${url}`, 'DISCOVERY_FAILED', { cause: error })
+  }
+  if (!response.ok) {
+    throw new LlmError(
+      `${url} answered ${response.status}${response.status === 401 || response.status === 403 ? '; check the API key' : ''}`,
+      'DISCOVERY_FAILED',
+    )
+  }
+  let text: string
+  try {
+    text = await readBounded(response, url)
+  } catch (error: unknown) {
+    // Cancellation during the body read rejects with the abort reason, which
+    // may be any value; the caller gets the same coded failure it would have
+    // for a cancellation before the request went out.
+    if (request.signal?.aborted) {
+      throw new LlmError('model discovery aborted by caller', 'ABORTED', { cause: error })
+    }
+    throw error
+  }
+  let body: unknown
+  try {
+    body = JSON.parse(text)
+  } catch (error: unknown) {
+    throw new LlmError(`${url} did not answer with JSON`, 'DISCOVERY_FAILED', { cause: error })
+  }
+  return readListing(body)
+}

package/src/index.ts

@@ -1,25 +1,42 @@
 /**
- * Register an {@link OllamaAdapter} for the `ollama-cloud-direct` provider route
- * on `ctx.llm`, with connection facts resolved once per operation from the
- * plugin's `cordis.yml` mount config and the bearer token resolved per request
- * through the credential seam (`ctx.credentials`), falling back to the
- * process environment.
+ * Register an {@link OllamaAdapter} for the `ollama-cloud-direct` provider
+ * route on `ctx.llm`, with connection facts resolved per request instead of
+ * frozen at load: the plugin layers its `cordis.yml` entry config under the
+ * optional `llm-ollama-cloud` user-settings section (`ctx.settings`) and
+ * resolves the bearer token through the credential seam (`ctx.credentials`),
+ * falling back to the process environment, so a changed base URL, catalog, or
+ * key reaches the very next request without restarting anything, while an
+ * in-flight stream keeps the facts it started with. The one
+ * registration-captured fact — the retry policy — re-registers the route in
+ * place when it changes.
+ *
+ * The route is configured pi-ai-style, as a per-route profile under
+ * `providers.ollama-cloud-direct`: with no stored profile the route is
+ * **dormant on configuration surfaces** — declared in the configurable-provider
+ * directory so the Models settings page lists it in the add-provider select —
+ * while the adapter itself serves the resolved defaults (schema defaults plus
+ * this module's fallbacks) the moment the plugin mounts, so an ambient
+ * `OLLAMA_CLOUD_API_KEY` keeps working before the page ever writes a profile.
+ * A model-discovery registration answers the page's fetch action from the
+ * resolved catalog, or interrogates a drafted endpoint.
  *
  * Dependencies are intentionally minimal — `@deepseek-ai/dsh-llm` (the harness
  * LLM seam contract), `@deepseek-ai/dsh-credentials` (the credential seam),
- * `@deepseek-ai/cordis` (plugin framework), and `eventsource-parser` (SSE
- * framing). There is no settings-section wiring and no schema library:
- * configuration is static from the mount, and validation is hand-rolled. The
- * route is `ollama-cloud-direct` (not `ollama-cloud`) so it can coexist with a
- * pi-ai-configured `ollama-cloud` route.
+ * `@deepseek-ai/dsh-settings` (the settings-section install), `@deepseek-ai/
+ * schemastery` (the section schema), `@deepseek-ai/cordis` (plugin framework),
+ * and `eventsource-parser` (SSE framing); validation beyond the schema is
+ * hand-rolled. The route is `ollama-cloud-direct` (not `ollama-cloud`) so it
+ * can coexist with a pi-ai-configured `ollama-cloud` route.
  *
  * @module llm-ollama-cloud
  */
 
 import type { Context } from '@deepseek-ai/cordis'
-import { credentialRef } from '@deepseek-ai/dsh-credentials'
-import { assertUsableApiKey, LlmError, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
+import z from '@deepseek-ai/schemastery'
+import { assertUsableApiKey, LlmError, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
 import type { ModelModality, RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import {
   DEFAULT_CONTEXT_WINDOW,
   DEFAULT_MAX_TOKENS,
@@ -29,6 +46,7 @@ import {
   OllamaAdapter,
 } from './adapter.ts'
 import type { OllamaCatalogModel, OllamaConnectionOptions } from './adapter.ts'
+import { discoverModels } from './discovery.ts'
 
 export {
   DEFAULT_CONTEXT_WINDOW,
@@ -39,15 +57,17 @@ export {
   OllamaAdapter,
 } from './adapter.ts'
 export type { OllamaAdapterOptions, OllamaCatalogModel, OllamaConnectionOptions } from './adapter.ts'
+export { discoverModels } from './discovery.ts'
 export type { RequestDefaults } from './serialize.ts'
 export type * from './types.ts'
 
 export const name = 'llm-ollama-cloud'
 export const inject = ['llm']
 
+const NS = settingsNamespace('llm-ollama-cloud')
 const DEFAULT_API_KEY_ENV = 'OLLAMA_CLOUD_API_KEY'
 /** The single provider route this plugin owns. */
-const PROVIDER = 'ollama-cloud-direct'
+export const PROVIDER = 'ollama-cloud-direct'
 
 const DEFAULT_MODELS: OllamaCatalogModel[] = [
   { id: 'deepseek-v4-flash:cloud', name: 'DeepSeek-V4-Flash (cloud)', contextWindow: DEFAULT_CONTEXT_WINDOW },
@@ -58,13 +78,15 @@ const DEFAULT_MODELS: OllamaCatalogModel[] = [
 const MODEL_MODALITIES = ['text', 'image'] as const satisfies readonly ModelModality[]
 
 /**
- * Plugin config from the `cordis.yml` mount entry. Every field is optional: a
- * missing API key fails per request with `MISSING_CREDENTIAL`, omitted
+ * One route's stored profile — the plugin config's per-route entry and the
+ * shape the Models page writes under `providers.<route>`. Every field is
+ * optional: a profile naming no reference resolves key material through
+ * {@link OllamaProviderProfile.apiKeyEnv}'s default at each request, omitted
  * thinking mode uses the provider default, and omitted reasoning effort lets
  * the server auto-enable thinking at its default.
  */
-export interface Config {
-  /** Environment-variable name resolved per request; defaults to `OLLAMA_CLOUD_API_KEY`. */
+export interface OllamaProviderProfile {
+  /** Credential reference (environment-variable name) resolved per request; defaults to `OLLAMA_CLOUD_API_KEY`. */
   apiKeyEnv?: string
   /** Endpoint base; defaults to the Ollama cloud API. */
   baseURL?: string
@@ -84,6 +106,47 @@ export interface Config {
   retryPolicy?: RetryPolicyConfig
 }
 
+/**
+ * Plugin config from the `cordis.yml` mount entry, validated by the
+ * same-named schemastery schema and doubling as the `llm-ollama-cloud`
+ * settings-section shape. Profiles are keyed by provider route id; the route
+ * this plugin serves is {@link PROVIDER}. A mount that pins the profile
+ * presents the route as configured; a bare mount leaves it dormant in the
+ * add-provider select until the page (or `settings.yaml`) writes one.
+ */
+export interface Config {
+  /** Per-route profiles keyed by provider route id. */
+  providers?: Record<string, OllamaProviderProfile>
+}
+
+/** The catalog-model entry schema (one profile's `models` row). */
+const catalogModel: z<OllamaCatalogModel> = z.object({
+  id: z.string().required(),
+  name: z.string(),
+  description: z.string(),
+  contextWindow: z.number().step(1).min(1),
+  maxTokens: z.number().step(1).min(1),
+  inputModalities: z.array(z.union(MODEL_MODALITIES)).min(1).default(['text']),
+})
+
+/** One stored route profile; its defaults apply only once the profile exists. */
+const profileSchema: z<OllamaProviderProfile> = z.object({
+  apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
+  baseURL: z.string(),
+  thinking: z.union(['enabled', 'disabled']),
+  reasoningEffort: z.union(['off', 'low', 'high', 'max']),
+  maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_TOKENS),
+  defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+  models: z.array(catalogModel).default(DEFAULT_MODELS),
+  streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  retryPolicy: RetryPolicySchema,
+})
+
+/** The `llm-ollama-cloud` settings-section schema; `Config` is its static type. */
+export const Config: z<Config> = z.object({
+  providers: z.dict(profileSchema).default({}),
+})
+
 /** The public Ollama cloud API base. */
 export const PUBLIC_BASE_URL = 'https://ollama.com/v1'
 
@@ -134,26 +197,38 @@ function resolveModels(models: readonly OllamaCatalogModel[] | undefined): Ollam
 }
 
 /**
- * The one explicit resolve step from raw mount config to validated connection
+ * The one explicit resolve step from raw config to validated connection
  * facts, with every default and bound re-judged here (fail loud at load).
- * @param config - raw plugin config.
- * @returns validated connection facts plus the credential reference.
+ * Programmatic construction may bypass Schemastery normalization, so this
+ * also re-judges each settings snapshot at its first use.
+ * @param config - raw plugin config or resolved settings snapshot.
+ * @returns validated connection facts for {@link PROVIDER}.
  */
 export function resolveAdapterOptions(config: Config): OllamaConnectionOptions {
-  if (config.thinking === 'disabled'
-    && config.reasoningEffort !== undefined
-    && config.reasoningEffort !== 'off') {
+  return resolveProfileOptions(config.providers?.[PROVIDER])
+}
+
+/**
+ * Resolve one raw profile into validated connection facts. A missing profile
+ * resolves the defaults, which is the dormant route's serving posture.
+ * @param profile - raw profile fields, or `undefined` when none is stored.
+ * @returns validated connection facts plus the credential reference.
+ */
+export function resolveProfileOptions(profile: OllamaProviderProfile | undefined): OllamaConnectionOptions {
+  if (profile?.thinking === 'disabled'
+    && profile.reasoningEffort !== undefined
+    && profile.reasoningEffort !== 'off') {
     throw new Error('llm-ollama-cloud: only reasoningEffort "off" can be configured when thinking is disabled')
   }
-  if (config.defaultContextWindow !== undefined
-    && (!Number.isInteger(config.defaultContextWindow) || config.defaultContextWindow <= 0)) {
+  if (profile?.defaultContextWindow !== undefined
+    && (!Number.isInteger(profile.defaultContextWindow) || profile.defaultContextWindow <= 0)) {
     throw new Error('llm-ollama-cloud: defaultContextWindow must be a positive integer')
   }
-  if (config.maxTokens !== undefined
-    && (!Number.isSafeInteger(config.maxTokens) || config.maxTokens <= 0)) {
+  if (profile?.maxTokens !== undefined
+    && (!Number.isSafeInteger(profile.maxTokens) || profile.maxTokens <= 0)) {
     throw new Error('llm-ollama-cloud: maxTokens must be a positive safe integer')
   }
-  const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
+  const streamIdleTimeoutMs = profile?.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
   if (!Number.isFinite(streamIdleTimeoutMs)
     || streamIdleTimeoutMs <= 0
     || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
@@ -162,17 +237,17 @@ export function resolveAdapterOptions(config: Config): OllamaConnectionOptions {
     )
   }
   return {
-    apiKeyEnv: config.apiKeyEnv ?? DEFAULT_API_KEY_ENV,
-    baseURL: config.baseURL ?? PUBLIC_BASE_URL,
+    apiKeyEnv: credentialRef(profile?.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
+    baseURL: profile?.baseURL ?? PUBLIC_BASE_URL,
     defaults: {
-      thinking: config.thinking,
-      reasoningEffort: config.reasoningEffort,
+      thinking: profile?.thinking,
+      reasoningEffort: profile?.reasoningEffort,
     },
-    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
-    defaultContextWindow: config.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
-    models: resolveModels(config.models),
+    maxTokens: profile?.maxTokens ?? DEFAULT_MAX_TOKENS,
+    defaultContextWindow: profile?.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
+    models: resolveModels(profile?.models),
     streamIdleTimeoutMs,
-    retryPolicy: resolveRetryPolicy(config.retryPolicy, 'llm-ollama-cloud: retryPolicy'),
+    retryPolicy: resolveRetryPolicy(profile?.retryPolicy, 'llm-ollama-cloud: retryPolicy'),
   }
 }
 
@@ -182,33 +257,96 @@ interface CredentialsLike {
 }
 
 export function apply(ctx: Context, config: Config = {}): void {
-  // Static composition: connection facts resolve once at load. A config
-  // change in the mount requires a restart — there is no settings section.
-  const options = (): OllamaConnectionOptions => resolveAdapterOptions(config)
-  const connection = options()
-  // Fail loud at load on a malformed credential reference name.
-  credentialRef(connection.apiKeyEnv)
-
-  const credentials = ctx.get('credentials') as CredentialsLike | undefined
-  const adapter = new OllamaAdapter({
-    options,
-    resolveApiKey: async (connection) => {
-      const ref = connection.apiKeyEnv
-      if (credentials !== undefined) {
-        const hit = await credentials.resolve(ref)
-        if (hit !== undefined && hit.value.length > 0) {
-          return assertUsableApiKey(hit.value, 'llm-ollama-cloud', ref)
-        }
-      }
-      const value = process.env[ref]
-      if (value !== undefined && value.length > 0) {
-        return assertUsableApiKey(value, 'llm-ollama-cloud', ref)
+  let current: () => Config = () => config
+  let lastRaw: Config | undefined
+  let lastGood: OllamaConnectionOptions | undefined
+  const options = (): OllamaConnectionOptions => {
+    const raw = current()
+    if (raw === lastRaw && lastGood !== undefined) return lastGood
+    try {
+      const next = resolveAdapterOptions(raw)
+      lastRaw = raw
+      lastGood = next
+      return next
+    } catch (error) {
+      // Static composition resolves before anything registers, so this branch
+      // only sees a live settings snapshot failing a beyond-schema bound:
+      // keep serving the last good facts and say so once per bad snapshot.
+      if (lastGood === undefined) throw error
+      lastRaw = raw
+      ctx.logger.error('llm-ollama-cloud: keeping the last good configuration after an invalid settings section')
+      ctx.logger.error(error)
+      return lastGood
+    }
+  }
+  options()
+
+  const resolveApiKey = async (connection: OllamaConnectionOptions): Promise<string> => {
+    // Every credential fact comes from the caller's snapshot, so a rejected
+    // settings generation cannot leak its key onto the previous endpoint.
+    const ref = connection.apiKeyEnv
+    const credentials = ctx.get('credentials') as CredentialsLike | undefined
+    if (credentials !== undefined) {
+      const hit = await credentials.resolve(ref)
+      if (hit !== undefined && hit.value.length > 0) {
+        return assertUsableApiKey(hit.value, 'llm-ollama-cloud', ref)
       }
-      throw new LlmError(
-        `llm-ollama-cloud: no API key for provider route "${PROVIDER}"; store ${ref} in the credentials file or export it in the launching environment`,
-        'MISSING_CREDENTIAL',
-      )
+    }
+    const ambient = process.env[ref]
+    if (ambient !== undefined && ambient.length > 0) {
+      return assertUsableApiKey(ambient, 'llm-ollama-cloud', ref)
+    }
+    throw new LlmError(
+      `llm-ollama-cloud: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials`
+      + ` service (the web Models page writes it), or export ${ref} in the launching environment`,
+      'MISSING_CREDENTIAL',
+    )
+  }
+  /**
+   * The stored credential, for a probe whose draft carries none. Missing is
+   * an answer here (`undefined`, probe unauthenticated), not a failure — the
+   * request path owns the loud MISSING_CREDENTIAL refusal.
+   */
+  const storedApiKey = async (): Promise<string | undefined> => {
+    const ref = options().apiKeyEnv
+    const credentials = ctx.get('credentials') as CredentialsLike | undefined
+    const hit = credentials !== undefined ? (await credentials.resolve(ref))?.value : undefined
+    const value = hit !== undefined && hit.length > 0 ? hit : process.env[ref]
+    return value !== undefined && value.length > 0 ? value : undefined
+  }
+
+  const adapter = new OllamaAdapter({ options, resolveApiKey })
+  // Declared even while dormant, so configuration surfaces list the route in
+  // the add-provider select before any profile exists.
+  ctx.llm.registerConfigurableProviders([
+    { provider: PROVIDER, displayName: 'Ollama Cloud', settingsNs: NS, settingsPath: ['providers', PROVIDER] },
+  ])
+  // Route effects bind to this apply fiber via the stable `ctx` reference,
+  // even when a swap runs inside the scoped settings callback below.
+  const registration = ctx.llm.registerAdapter([PROVIDER], adapter)
+  let registeredPolicy = options().retryPolicy
+  const ensureRegistrationFacts = (): void => {
+    const policy = options().retryPolicy
+    if (deepEqualJson(policy, registeredPolicy)) return
+    // The registry captures the retry policy at registration, so it is the one
+    // fact per-request resolution cannot refresh. `replace` re-reads it in one
+    // synchronous registry section: disposing and re-registering instead would
+    // publish an empty route set between the two, and an observer that reacted
+    // to it would see this provider disappear and come back.
+    registration.replace([PROVIDER])
+    registeredPolicy = policy
+  }
+  // The Models page's fetch action: a draft naming this route answers from the
+  // resolved catalog; anything else is interrogated at the endpoint it shows.
+  ctx.llm.registerModelDiscovery(NS, (request, signal) => discoverModels(
+    { ...request, ...signal === undefined ? {} : { signal } },
+    options().models,
+    storedApiKey,
+  ))
+  installSettingsSection(ctx, NS, Config, config, {
+    setSource: (source) => {
+      current = source
     },
+    onChange: ensureRegistrationFacts,
   })
-  ctx.llm.registerAdapter([PROVIDER], adapter)
 }