Merge branch 'worktree-llm-dynamic-config' into worktree-llm-web-config

# Conflicts: # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/event-producer-consumer.md # examples/headless-agent/tests/headless.snapshot.ts # examples/headless-agent/tests/snapshots/missing-credential/stream-json.expected.jsonl # packages/llm/llm-deepseek/README.i18n.yaml # packages/llm/llm-deepseek/src/index.ts # packages/llm/llm-pi-ai/README.i18n.yaml # packages/llm/llm-pi-ai/src/index.ts # packages/llm/llm/README.i18n.yaml # packages/llm/llm/src/index.ts
2026-07-30 17:22:44 +08:00
parent 8707f324c6 a90ccc4453
commit 0a263941ef
60 changed files with 1320 additions and 320 deletions
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/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
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/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-official'

 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,19 +207,20 @@ 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-official"; 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',
    )
  }

  const adapter = new DeepSeekAdapter({ options, resolveApiKey })
  ctx.llm.registerConfigurableProviders([
-    { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: NS, settingsPath: [] },
+    { 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.
-  let disposeRoute = ctx.llm.registerAdapter(['deepseek-official'], adapter)
+  let disposeRoute = ctx.llm.registerAdapter([PROVIDER], adapter)
  let registeredPolicy = options().retryPolicy
  const ensureRegistrationFacts = (): void => {
    const policy = options().retryPolicy
@@ -223,17 +229,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-official'], 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-official"; requests will fail until one is configured')
-  })
-
  installSettingsSection(ctx, NS, Config, config, {
    setSource: (source) => {
      current = source