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-pi-ai/src/adapter.ts

@@ -41,9 +41,11 @@ export interface PiAiAdapterOptions {
   /**
    * Resolve the credential for one already-resolved profile; called once per
    * stream call and frozen for that call. `undefined` defers to pi-ai's
-   * provider-native ambient discovery.
+   * provider-native ambient discovery, which the plugin allows only for a
+   * profile naming no credential at all; a named reference that misses throws
+   * `LlmError` `MISSING_CREDENTIAL` rather than falling back.
    */
-  resolveApiKey: (profile: ResolvedPiAiProviderProfile) => Promise<string | undefined>
+  resolveApiKey: (provider: string, profile: ResolvedPiAiProviderProfile) => Promise<string | undefined>
 }
 
 /**
@@ -180,7 +182,7 @@ export class PiAiAdapter extends LlmAdapter {
       model,
       options.reasoningEffort ?? profile.reasoning,
     )
-    const apiKey = await this.config.resolveApiKey(profile)
+    const apiKey = await this.config.resolveApiKey(options.provider, profile)
 
     const consumer = new AbortController()
     const upstream = options.signal === undefined

packages/llm/llm-pi-ai/src/index.ts

@@ -29,7 +29,8 @@
  */
 
 import type { Context } from 'cordis'
-import type {} from '@deepseek-ai/dsh-llm'
+import { LlmError } from '@deepseek-ai/dsh-llm'
+import type { AdapterRegistrationHandle } from '@deepseek-ai/dsh-llm'
 import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { PiAiAdapter } from './adapter.ts'
 import { Config, resolveProfiles } from './config.ts'
@@ -45,9 +46,15 @@ export const inject = ['llm']
 
 const NS = settingsNamespace('llm-pi-ai')
 
-/** The registry captures these per route; a change here must re-register. */
+/**
+ * The registry captures these per route; a change here must re-register.
+ * Sorted by provider so a settings document that merely reorders its keys is
+ * not mistaken for a route change.
+ */
 function registrationFacts(profiles: ReadonlyMap<string, ResolvedPiAiProviderProfile>): unknown {
-  return [...profiles.entries()].map(([provider, profile]) => ({ provider, retryPolicy: profile.retryPolicy }))
+  return [...profiles.entries()]
+    .map(([provider, profile]) => ({ provider, retryPolicy: profile.retryPolicy }))
+    .sort((left, right) => left.provider < right.provider ? -1 : left.provider > right.provider ? 1 : 0)
 }
 
 /** Register one generic pi-ai adapter for all configured provider routes. */
@@ -76,17 +83,31 @@ export function apply(ctx: Context, config: Config): void {
   }
   profiles()
 
-  const resolveApiKey = async (profile: ResolvedPiAiProviderProfile): Promise<string | undefined> => {
+  const resolveApiKey = async (
+    provider: string,
+    profile: ResolvedPiAiProviderProfile,
+  ): Promise<string | undefined> => {
     if (profile.apiKey !== undefined) return profile.apiKey
     const ref = profile.apiKeyEnv
+    // Only a profile that names no credential at all defers to pi-ai's
+    // provider-native discovery. Once one is named, a miss must fail loud:
+    // handing pi-ai `undefined` would let it pick up an unrelated ambient key
+    // (OPENAI_API_KEY and friends), billing another tenant for a request the
+    // deployment meant to authenticate differently.
     if (ref === undefined) return undefined
     const credentials = ctx.get('credentials')
-    if (credentials !== undefined) return (await credentials.resolve(ref))?.value
-    // Without the seam, keep an ambient fallback so a plain cordis.yml
-    // composition works from the environment alone; an empty variable defers
-    // to pi-ai's own provider-native discovery like an absent one.
-    const ambient = process.env[ref]
-    return ambient !== undefined && ambient.length > 0 ? ambient : undefined
+    const hit = credentials !== undefined
+      ? (await credentials.resolve(ref))?.value
+      // Without the seam, read exactly the named variable so a plain
+      // cordis.yml composition works from the environment alone.
+      : process.env[ref]
+    if (hit !== undefined && hit.length > 0) return hit
+    throw new LlmError(
+      `llm-pi-ai: no credential for provider route "${provider}"; its profile resolves ${ref}, which is not`
+      + ` set — store ${ref} through the credentials service (the web Models page writes it) or export it,`
+      + ' and remove apiKeyEnv only if this provider should authenticate from pi-ai\'s own environment discovery',
+      'MISSING_CREDENTIAL',
+    )
   }
 
   const adapter = new PiAiAdapter({ profiles, resolveApiKey })
@@ -94,18 +115,29 @@ export function apply(ctx: Context, config: Config): void {
   // even when a swap runs inside the scoped settings callback below. A bare
   // mount (zero routes) is the dormant posture: nothing registers until a
   // settings section supplies profiles, and routes drop when it empties.
-  let disposeRoutes: (() => void) | undefined
+  let registration: AdapterRegistrationHandle | undefined
   let registeredFacts: unknown
   const ensureRegistrationFacts = (): void => {
     const facts = registrationFacts(profiles())
     if (deepEqualJson(facts, registeredFacts)) return
     // The registry captures the route set and each route's retry policy at
-    // registration: swap the registration in one synchronous section (same
-    // adapter instance, no NO_ADAPTER window).
-    disposeRoutes?.()
-    disposeRoutes = undefined
+    // registration, so a change to either must re-register. The swap is
+    // atomic (same adapter instance, validated before anything moves): a
+    // conflicting route leaves the previous routes serving requests, and
+    // `registeredFacts` only advances once the registry actually holds the
+    // new set — so returning to a working configuration always re-applies.
     const routes = [...profiles().keys()]
-    if (routes.length > 0) disposeRoutes = ctx.llm.registerAdapter(routes, adapter)
+    if (registration === undefined) {
+      // Dormant bare mount: nothing is registered until a section supplies
+      // profiles, and an empty section keeps it that way.
+      if (routes.length === 0) {
+        registeredFacts = facts
+        return
+      }
+      registration = ctx.llm.registerAdapter(routes, adapter)
+    } else {
+      registration.replace(routes)
+    }
     registeredFacts = facts
   }
   ensureRegistrationFacts()