fix(llm): atomic route replacement, whole-snapshot requests, and loud credential misses

Four review findings across the seam and both adapters.

registerAdapter now returns a handle carrying replace(providers): the
candidate route set is validated in full before anything moves, so a
route another adapter owns leaves the previous registration intact, and
the swap itself is one synchronous section with no observable gap. pi-ai
uses it instead of dispose-then-register — the old shape dropped every
route when the new set conflicted, and its facts cache could then equal
the registry's, so reverting to a working configuration never re-applied.
Its registration facts are also sorted by provider, so a settings
document that merely reorders keys no longer triggers a swap.

DeepSeek's per-request snapshot now carries the credential facts, and
resolveApiKey receives it instead of re-reading the raw config: a
settings generation the resolver rejects can no longer contribute its
literal key to a request the previous generation's endpoint serves.

pi-ai only defers to the SDK's provider-native discovery when a profile
names no credential at all; a configured apiKeyEnv that misses now fails
with MISSING_CREDENTIAL naming the route and the reference, instead of
handing pi-ai undefined and letting it authenticate with an unrelated
ambient key.

The eager boot-time credential probe is gone: it could run before the
credentials service mounted and reported every failure as a missing key.
The route stays registered and browsable; the first request gives the
accurate error, whose guidance now leads with the credential store and
mentions a literal apiKey last.

packages/llm/llm-deepseek/src/adapter.ts

@@ -17,6 +17,7 @@ import type {
   ResolvedRetryPolicy,
   StreamChunk,
 } from '@deepseek-ai/dsh-llm'
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { serializeRequest } from './serialize.ts'
 import type { RequestDefaults } from './serialize.ts'
@@ -45,6 +46,14 @@ export interface DeepSeekCatalogModel {
 export interface DeepSeekConnectionOptions {
   /** Endpoint base; `/chat/completions` is appended. */
   baseURL: string
+  /**
+   * Literal API key of this same resolution, when the configuration carried
+   * one. Travelling with the endpoint is the point: a request can never pair
+   * one generation's URL with another generation's secret.
+   */
+  apiKey?: string
+  /** Credential reference of this same resolution, resolved per request when no literal key exists. */
+  apiKeyEnv: CredentialRef
   /** Request defaults applied to every call (thinking mode, effort). */
   defaults: RequestDefaults
   /** Positive context capacity used when the selected model has no exact value. */
@@ -62,11 +71,12 @@ export interface DeepSeekAdapterOptions {
   /** Current validated connection facts; called once per operation. */
   options: () => DeepSeekConnectionOptions
   /**
-   * Resolve the bearer token for one request; called once per stream call and
-   * frozen for that call. Throws `LlmError` `MISSING_CREDENTIAL` when no key
-   * is available anywhere.
+   * Resolve the bearer token for the connection facts of one request. The
+   * snapshot is passed in — never re-read — so the key can only ever come
+   * from the same resolution as the endpoint it is sent to. Throws `LlmError`
+   * `MISSING_CREDENTIAL` when no key is available anywhere.
    */
-  resolveApiKey: () => Promise<string>
+  resolveApiKey: (connection: DeepSeekConnectionOptions) => Promise<string>
 }
 
 /** Default maximum idle interval while an adapter stream read is outstanding. */
@@ -189,8 +199,10 @@ export class DeepSeekAdapter extends LlmAdapter {
     // One resolution per stream call: connection facts and the credential
     // freeze here and hold for this whole request, so an in-flight stream
     // never observes a configuration change and the next call re-resolves.
+    // The key resolves *from this snapshot*, so an endpoint and the secret
+    // sent to it can never come from different configuration generations.
     const connection = this.config.options()
-    const apiKey = await this.config.resolveApiKey()
+    const apiKey = await this.config.resolveApiKey(connection)
     const consumer = new AbortController()
     const upstream = options.signal === undefined
       ? consumer.signal

packages/llm/llm-deepseek/src/index.ts

@@ -16,7 +16,6 @@ import z from 'schemastery'
 import { LlmError, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
 import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
-import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter } from './adapter.ts'
@@ -32,6 +31,8 @@ export const inject = ['llm']
 
 const NS = settingsNamespace('llm-deepseek')
 const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY'
+/** The single provider route this plugin owns. */
+const PROVIDER = 'deepseek'
 
 const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
   { id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', contextWindow: 256_000 },
@@ -89,11 +90,13 @@ export const Config: z<Config> = z.object({
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
 export const PUBLIC_BASE_URL = 'https://api.deepseek.com'
 
-/** Connection facts plus the plugin-consumed credential reference. */
-export interface ResolvedDeepSeekOptions extends DeepSeekConnectionOptions {
-  /** Reference resolved per request when no literal key is configured. */
-  apiKeyEnv: CredentialRef
-}
+/**
+ * One resolution's complete request facts. Connection and credential facts
+ * are one value on purpose: a snapshot the resolver rejects keeps the whole
+ * previous generation, so a request can never pair a stale endpoint with a
+ * newer key.
+ */
+export type ResolvedDeepSeekOptions = DeepSeekConnectionOptions
 
 /** Resolve, validate, and detach the advisory model catalog. */
 function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): DeepSeekCatalogModel[] {
@@ -147,6 +150,7 @@ export function resolveAdapterOptions(config: Config): ResolvedDeepSeekOptions {
     )
   }
   return {
+    ...config.apiKey !== undefined && config.apiKey.length > 0 ? { apiKey: config.apiKey } : {},
     apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
     baseURL: config.baseURL ?? process.env.DEEPSEEK_BASE_URL ?? PUBLIC_BASE_URL,
     defaults: {
@@ -187,10 +191,11 @@ export function apply(ctx: Context, config: Config): void {
   }
   options()
 
-  const resolveApiKey = async (): Promise<string> => {
-    const raw = current()
-    if (raw.apiKey !== undefined && raw.apiKey.length > 0) return raw.apiKey
-    const ref = options().apiKeyEnv
+  const resolveApiKey = async (connection: ResolvedDeepSeekOptions): Promise<string> => {
+    // Every credential fact comes from the caller's snapshot, so a rejected
+    // settings generation cannot leak its key onto the previous endpoint.
+    if (connection.apiKey !== undefined) return connection.apiKey
+    const ref = connection.apiKeyEnv
     const credentials = ctx.get('credentials')
     if (credentials !== undefined) {
       const hit = await credentials.resolve(ref)
@@ -202,8 +207,9 @@ export function apply(ctx: Context, config: Config): void {
       if (ambient !== undefined && ambient.length > 0) return ambient
     }
     throw new LlmError(
-      'llm-deepseek: no API key for provider route "deepseek"; set the llm-deepseek "apiKey" setting,'
-      + ` store ${ref} with the credentials service, or export ${ref}`,
+      `llm-deepseek: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials`
+      + ` service (the web Models page writes it), export ${ref} in the launching environment, or — as a`
+      + ' last resort — set a literal "apiKey" in the llm-deepseek settings section',
       'MISSING_CREDENTIAL',
     )
   }
@@ -211,7 +217,7 @@ export function apply(ctx: Context, config: Config): void {
   const adapter = new DeepSeekAdapter({ options, resolveApiKey })
   // Route effects bind to this apply fiber via the stable `ctx` reference,
   // even when a swap runs inside the scoped settings callback below.
-  let disposeRoute = ctx.llm.registerAdapter(['deepseek'], adapter)
+  let disposeRoute = ctx.llm.registerAdapter([PROVIDER], adapter)
   let registeredPolicy = options().retryPolicy
   const ensureRegistrationFacts = (): void => {
     const policy = options().retryPolicy
@@ -220,17 +226,10 @@ export function apply(ctx: Context, config: Config): void {
     // fact per-request resolution cannot refresh: swap the registration in one
     // synchronous section (same adapter instance, no NO_ADAPTER window).
     disposeRoute()
-    disposeRoute = ctx.llm.registerAdapter(['deepseek'], adapter)
+    disposeRoute = ctx.llm.registerAdapter([PROVIDER], adapter)
     registeredPolicy = policy
   }
 
-  void resolveApiKey().then(() => undefined, () => {
-    // Expected on a first boot with dynamic sources: the route stays
-    // registered (the catalog is browsable) and each request fails with the
-    // actionable MISSING_CREDENTIAL message until a key arrives.
-    ctx.logger.warn('llm-deepseek: no API key resolved yet for route "deepseek"; requests will fail until one is configured')
-  })
-
   installSettingsSection(ctx, NS, Config, config, {
     setSource: (source) => {
       current = source