Merge commit 'refs/codex/pr1006/master' into worktree/pr1006-merge-20260731

# Conflicts: # docs/architecture.i18n.yaml # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # examples/headless-agent/cordis.yml # packages/cordis/tool-cordis/src/api-catalog.ts # packages/llm/llm-deepseek/README.i18n.yaml # packages/llm/llm-deepseek/README.md # packages/llm/llm-deepseek/README.zh.md # packages/llm/llm-deepseek/src/adapter.ts # packages/llm/llm-deepseek/src/index.ts # packages/llm/llm-deepseek/tests/adapter.spec.ts # packages/llm/llm/README.i18n.yaml # packages/llm/llm/README.md # packages/llm/llm/README.zh.md # packages/subagent/subagent-dsh-sdk/README.i18n.yaml # packages/ui/jsonrpc/README.i18n.yaml
2026-07-31 01:55:19 +08:00
parent 9a0ee6fbfe c61a05ca5f
commit 464a57d3ca
664 changed files with 19076 additions and 2562 deletions
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -1,21 +1,24 @@
 /**
 * `DeepSeekAdapter`: fetch + SSE against a DeepSeek (OpenAI-compatible)
- * chat-completions endpoint, emitting harness StreamChunks.
+ * chat-completions endpoint, emitting harness StreamChunks. The adapter is
+ * transport-only: connection facts arrive through a thunk resolved once per
+ * operation and the bearer token through a per-request resolver, so the
+ * registering plugin owns validation, layering, and credential policy.
 *
 * @module dsh-llm-deepseek/adapter
 */

-import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
+import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import type {
  GenerateOptions,
  LlmModelInfo,
  LlmProviderInfo,
  LlmResolvedModelInfo,
  ResolvedRetryPolicy,
-  RetryPolicyConfig,
  StreamChunk,
 } from '@deepseek-ai/dsh-llm'
-import { idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf } from '@deepseek-ai/dsh-timeout'
+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'
 import { parseSse } from './sse.ts'
@@ -34,24 +37,48 @@ export interface DeepSeekCatalogModel {
  contextWindow?: number
 }

-/** Constructor options for {@link DeepSeekAdapter}; the plugin's `apply` resolves them from Config + environment. */
-export interface DeepSeekAdapterOptions {
-  /** Bearer token sent in the `authorization` header on every request. */
-  apiKey: string
+/**
+ * Validated connection facts for one operation. The plugin's
+ * `resolveAdapterOptions` is the one explicit resolve step producing this
+ * shape; the adapter trusts it and re-reads it per operation, which is what
+ * makes a configuration change reach the next request without re-registration.
+ */
+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
+  defaults: RequestDefaults
  /** Default per-request output cap; explicit request values win. */
-  maxTokens?: number
+  maxTokens: number
  /** Positive context capacity used when the selected model has no exact value. */
-  defaultContextWindow?: number
+  defaultContextWindow: number
  /** Advisory models exposed to discovery consumers; requests remain unrestricted. */
-  models?: readonly DeepSeekCatalogModel[]
+  models: readonly DeepSeekCatalogModel[]
  /** Maximum provider idle time while one stream read is outstanding. */
-  streamIdleTimeoutMs?: number
-  /** Provider-owned model-request retry policy; omission uses normal defaults. */
-  retryPolicy?: RetryPolicyConfig
+  streamIdleTimeoutMs: number
+  /** Provider-owned model-request retry policy, already resolved. */
+  retryPolicy: ResolvedRetryPolicy
+}
+
+/** Constructor options for {@link DeepSeekAdapter}: the two resolution seams the plugin owns. */
+export interface DeepSeekAdapterOptions {
+  /** Current validated connection facts; called once per operation. */
+  options: () => DeepSeekConnectionOptions
+  /**
+   * 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: (connection: DeepSeekConnectionOptions) => Promise<string>
 }

 /** Default maximum idle interval while an adapter stream read is outstanding. */
@@ -124,35 +151,8 @@ export function httpErrorCode(status: number, error?: WireError['error']): strin
 * map to `ABORTED`; the configured per-read idle watchdog maps to `TIMEOUT`.
 */
 export class DeepSeekAdapter extends LlmAdapter {
-  private readonly streamIdleTimeoutMs: number
-  private readonly retryPolicy: ResolvedRetryPolicy
-  private readonly defaultContextWindow: number
-  private readonly maxTokens: number
-
-  constructor(private readonly options: DeepSeekAdapterOptions) {
+  constructor(private readonly config: DeepSeekAdapterOptions) {
    super()
-    if (options.defaults?.thinking === 'disabled'
-      && options.defaults.reasoningEffort !== undefined
-      && options.defaults.reasoningEffort !== 'off') {
-      throw new Error('llm-deepseek: only reasoningEffort "off" can be configured when thinking is disabled')
-    }
-    this.defaultContextWindow = options.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW
-    if (!Number.isInteger(this.defaultContextWindow) || this.defaultContextWindow <= 0) {
-      throw new Error('llm-deepseek: defaultContextWindow must be a positive integer')
-    }
-    this.maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS
-    if (!Number.isSafeInteger(this.maxTokens) || this.maxTokens <= 0) {
-      throw new Error('llm-deepseek: maxTokens must be a positive safe integer')
-    }
-    this.streamIdleTimeoutMs = options.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
-    if (!Number.isFinite(this.streamIdleTimeoutMs)
-      || this.streamIdleTimeoutMs <= 0
-      || this.streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
-      throw new Error(
-        `llm-deepseek: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`,
-      )
-    }
-    this.retryPolicy = resolveRetryPolicy(options.retryPolicy, 'llm-deepseek: retryPolicy')
  }

  override providerInfo(provider: string): LlmProviderInfo {
@@ -160,11 +160,11 @@ export class DeepSeekAdapter extends LlmAdapter {
  }

  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
-    return this.retryPolicy
+    return this.config.options().retryPolicy
  }

  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
-    return Promise.resolve((this.options.models ?? []).map(model => modelInfo(provider, model)))
+    return Promise.resolve(this.config.options().models.map(model => modelInfo(provider, model)))
  }

  override resolveModel(
@@ -172,16 +172,17 @@ export class DeepSeekAdapter extends LlmAdapter {
    model: string,
    _signal?: AbortSignal,
  ): Promise<LlmResolvedModelInfo> {
-    const configured = this.options.models?.find(entry => entry.id === model)
+    const connection = this.config.options()
+    const configured = connection.models.find(entry => entry.id === model)
    const contextWindow = configured?.contextWindow
-      ?? this.defaultContextWindow
+      ?? connection.defaultContextWindow
    return Promise.resolve({
      ...configured === undefined
        ? { provider, id: model, name: model }
        : modelInfo(provider, configured),
      context: { contextWindow },
-      defaultMaxTokens: this.maxTokens,
-      ...this.options.defaults?.thinking === 'disabled'
+      defaultMaxTokens: connection.maxTokens,
+      ...connection.defaults.thinking === 'disabled'
        ? {
          reasoning: {
            efforts: OFF_ONLY_REASONING_EFFORTS,
@@ -191,9 +192,9 @@ export class DeepSeekAdapter extends LlmAdapter {
        : {
          reasoning: {
            efforts: REASONING_EFFORTS,
-            defaultEffort: this.options.defaults?.reasoningEffort === 'off'
+            defaultEffort: connection.defaults.reasoningEffort === 'off'
              ? OFF_REASONING_EFFORT
-              : this.options.defaults?.reasoningEffort === 'max'
+              : connection.defaults.reasoningEffort === 'max'
                ? MAX_REASONING_EFFORT
                : HIGH_REASONING_EFFORT,
          },
@@ -202,12 +203,19 @@ export class DeepSeekAdapter extends LlmAdapter {
  }

  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    // 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(connection)
    const consumer = new AbortController()
    const upstream = options.signal === undefined
      ? consumer.signal
      : AbortSignal.any([options.signal, consumer.signal])
-    using watchdog = idleWatchdog(upstream, this.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE)
-    const iterator = this.request(options, watchdog.signal)[Symbol.asyncIterator]()
+    using watchdog = idleWatchdog(upstream, connection.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE)
+    const iterator = this.request(options, watchdog.signal, connection, apiKey)[Symbol.asyncIterator]()
    let exhausted = false
    try {
      while (true) {
@@ -221,7 +229,7 @@ export class DeepSeekAdapter extends LlmAdapter {
    } catch (error: unknown) {
      if (timeoutOf(watchdog.signal, STREAM_IDLE_TIMEOUT_CODE) !== undefined) {
        throw new LlmError(
-          `DeepSeek stream idle timeout after ${this.streamIdleTimeoutMs}ms`,
+          `DeepSeek stream idle timeout after ${connection.streamIdleTimeoutMs}ms`,
          'TIMEOUT',
          { cause: error },
        )
@@ -230,7 +238,7 @@ export class DeepSeekAdapter extends LlmAdapter {
        throw new LlmError('DeepSeek request aborted by caller', 'ABORTED', { cause: error })
      }
      if (error instanceof LlmError) throw error
-      throw new LlmError(`DeepSeek API stream from ${this.options.baseURL} failed`, 'TRANSPORT', { cause: error })
+      throw new LlmError(`DeepSeek API stream from ${connection.baseURL} failed`, 'TRANSPORT', { cause: error })
    } finally {
      consumer.abort('DeepSeek stream consumer stopped')
      if (!exhausted && iterator.return !== undefined) {
@@ -243,13 +251,18 @@ export class DeepSeekAdapter extends LlmAdapter {
    }
  }

-  private async * request(options: GenerateOptions, signal: AbortSignal): AsyncIterable<StreamChunk> {
-    const body = serializeRequest(options, this.options.defaults)
+  private async * request(
+    options: GenerateOptions,
+    signal: AbortSignal,
+    connection: DeepSeekConnectionOptions,
+    apiKey: string,
+  ): AsyncIterable<StreamChunk> {
+    const body = serializeRequest(options, connection.defaults)
    // Prepared outside the try so the TRANSPORT label below covers exactly the
    // transport boundary, never a serialization failure.
    const payload = JSON.stringify(body)
    const headers = {
-      'authorization': `Bearer ${this.options.apiKey}`,
+      'authorization': `Bearer ${apiKey}`,
      'content-type': 'application/json',
      'accept': 'text/event-stream',
      ...attributionHeaders(),
@@ -265,7 +278,7 @@ export class DeepSeekAdapter extends LlmAdapter {
    // outweighs its additional runtime dependencies.
    let response: Response
    try {
-      response = await fetch(`${this.options.baseURL}/chat/completions`, {
+      response = await fetch(`${connection.baseURL}/chat/completions`, {
        method: 'POST',
        headers,
        body: payload,
@@ -279,7 +292,7 @@ export class DeepSeekAdapter extends LlmAdapter {
      // lives on `cause`. Wrapping with the endpoint and chaining the cause
      // lets `errorChain` render the full diagnosis at every reporting seam.
      throw new LlmError(
-        `DeepSeek API request to ${this.options.baseURL} failed`,
+        `DeepSeek API request to ${connection.baseURL} failed`,
        'TRANSPORT',
        { cause: error },
      )
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -1,14 +1,22 @@
 /**
- * Register a {@link DeepSeekAdapter} for the `deepseek` provider route on `ctx.llm`. Configuration uses
- * Cordis schemastery; pass secrets from environment variables through `cordis.yml` with `!!js`,
- * as shown in the package README, rather than reading ad hoc files.
+ * Register a {@link DeepSeekAdapter} for the `deepseek-official` 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-deepseek` user-settings section (`ctx.settings`) and resolves the API
+ * key through the optional credential seam (`ctx.credentials`), 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.
 * @module @deepseek-ai/dsh-llm-deepseek
 */

 import type { Context } from 'cordis'
 import z from 'schemastery'
-import { RetryPolicySchema } from '@deepseek-ai/dsh-llm'
+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 { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import {
  DEFAULT_CONTEXT_WINDOW,
@@ -16,7 +24,7 @@ import {
  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
  DeepSeekAdapter,
 } from './adapter.ts'
-import type { DeepSeekCatalogModel } from './adapter.ts'
+import type { DeepSeekCatalogModel, DeepSeekConnectionOptions } from './adapter.ts'

 export {
  DEFAULT_CONTEXT_WINDOW,
@@ -24,28 +32,36 @@ export {
  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
  DeepSeekAdapter,
 } from './adapter.ts'
-export type { DeepSeekAdapterOptions, DeepSeekCatalogModel } from './adapter.ts'
+export type { DeepSeekAdapterOptions, DeepSeekCatalogModel, DeepSeekConnectionOptions } from './adapter.ts'
 export type { RequestDefaults } from './serialize.ts'
 export type * from './types.ts'

 export const name = 'llm-deepseek'
 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-official'
+
 const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
  { id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', contextWindow: DEFAULT_CONTEXT_WINDOW },
  { id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro', contextWindow: DEFAULT_CONTEXT_WINDOW },
 ]

 /**
- * Plugin config, validated by the same-named schemastery schema. Every field
- * is optional in yml: credentials/endpoint fall back to the environment (a
- * missing API key fails plugin load, not the first call), omitted thinking
- * mode uses the provider default, and omitted reasoning effort resolves to
- * `high`.
+ * Plugin config, validated by the same-named schemastery schema and doubling
+ * as the `llm-deepseek` settings-section shape. Every field is optional in
+ * yml: a missing API key resolves through {@link Config.apiKeyEnv} at each
+ * request (a request without any key fails with `MISSING_CREDENTIAL`, not at
+ * plugin load), omitted thinking mode uses the provider default, and omitted
+ * reasoning effort resolves to `high`.
 */
 export interface Config {
-  /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
+  /** Literal API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
  apiKey?: string
+  /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
+  apiKeyEnv?: string
  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL, then the public API. */
  baseURL?: string
  /** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
@@ -72,7 +88,8 @@ const catalogModel: z<DeepSeekCatalogModel> = z.object({
 })

 export const Config: z<Config> = z.object({
-  apiKey: z.string(),
+  apiKey: z.string().role('secret'),
+  apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
  baseURL: z.string(),
  thinking: z.union(['enabled', 'disabled']),
  reasoningEffort: z.union(['off', 'high', 'max']),
@@ -86,6 +103,14 @@ 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'

+/**
+ * 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[] {
  const seen = new Set<string>()
@@ -111,20 +136,40 @@ function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): Dee
  })
 }

-export function apply(ctx: Context, config: Config): void {
+/**
+ * The one explicit resolve step from raw config to validated connection
+ * facts. Programmatic construction may bypass Schemastery normalization, so
+ * every default and bound is re-judged here — for the composition entry at
+ * load (fail loud) and for each settings snapshot at its first use.
+ * @param config - raw plugin config or resolved settings snapshot.
+ * @returns validated connection facts plus the credential reference.
+ */
+export function resolveAdapterOptions(config: Config): ResolvedDeepSeekOptions {
  if (config.thinking === 'disabled'
    && config.reasoningEffort !== undefined
    && config.reasoningEffort !== 'off') {
    throw new Error('llm-deepseek: only reasoningEffort "off" can be configured when thinking is disabled')
  }
-  const apiKey = config.apiKey ?? process.env.DEEPSEEK_API_KEY
-  if (apiKey === undefined || apiKey.length === 0) {
-    throw new Error('llm-deepseek: an API key is required (Config.apiKey or $DEEPSEEK_API_KEY)')
+  if (config.defaultContextWindow !== undefined
+    && (!Number.isInteger(config.defaultContextWindow) || config.defaultContextWindow <= 0)) {
+    throw new Error('llm-deepseek: defaultContextWindow must be a positive integer')
  }
-  const baseURL = config.baseURL ?? process.env.DEEPSEEK_BASE_URL ?? PUBLIC_BASE_URL
-  ctx.llm.registerAdapter(['deepseek'], new DeepSeekAdapter({
-    apiKey,
-    baseURL,
+  if (config.maxTokens !== undefined
+    && (!Number.isSafeInteger(config.maxTokens) || config.maxTokens <= 0)) {
+    throw new Error('llm-deepseek: maxTokens must be a positive safe integer')
+  }
+  const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS
+  if (!Number.isFinite(streamIdleTimeoutMs)
+    || streamIdleTimeoutMs <= 0
+    || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(
+      `llm-deepseek: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`,
+    )
+  }
+  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: {
      thinking: config.thinking,
      reasoningEffort: config.reasoningEffort,
@@ -132,7 +177,83 @@ export function apply(ctx: Context, config: Config): void {
    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
    defaultContextWindow: config.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
    models: resolveModels(config.models),
-    streamIdleTimeoutMs: config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS,
-    ...config.retryPolicy === undefined ? {} : { retryPolicy: config.retryPolicy },
-  }))
+    streamIdleTimeoutMs,
+    retryPolicy: resolveRetryPolicy(config.retryPolicy, 'llm-deepseek: retryPolicy'),
+  }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  let current: () => Config = () => config
+  let lastRaw: Config | undefined
+  let lastGood: ResolvedDeepSeekOptions | undefined
+  const options = (): ResolvedDeepSeekOptions => {
+    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-deepseek: keeping the last good configuration after an invalid settings section')
+      ctx.logger.error(error)
+      return lastGood
+    }
+  }
+  options()
+
+  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)
+      if (hit !== undefined) return hit.value
+    } else {
+      // Without the seam, keep the historical ambient fallback so a plain
+      // cordis.yml composition works from the environment alone.
+      const ambient = process.env[ref]
+      if (ambient !== undefined && ambient.length > 0) return ambient
+    }
+    throw new LlmError(
+      `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',
+    )
+  }
+
+  const adapter = new DeepSeekAdapter({ options, resolveApiKey })
+  ctx.llm.registerConfigurableProviders([
+    { provider: PROVIDER, displayName: 'DeepSeek', settingsNs: NS, settingsPath: [] },
+  ])
+  // 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
+  }
+
+  installSettingsSection(ctx, NS, Config, config, {
+    setSource: (source) => {
+      current = source
+    },
+    onChange: ensureRegistrationFacts,
+  })
 }