Merge remote-tracking branch 'origin/master' into codex/simp-prune-llm-contract

# Conflicts:
#	docs/cordis-catalog/services.md
#	packages/llm/llm-pi-ai/README.md
#	packages/support/llm-replay/tests/llm-replay.spec.ts

packages/llm/llm-deepseek/README.md

@@ -2,7 +2,7 @@
 
 DeepSeek chat-completions adapter for the harness LLM seam: hand-rolled `fetch` + SSE translation from the official wire format (source of truth: the API docs — guides/thinking_mode, guides/tool_calls, api/create-chat-completion) into the `StreamChunk` protocol.
 
-A second, independent implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai` (library-backed). Same Config shape — pick one per context (registering both for the same model names throws by design).
+A second, library-backed implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai`. This package always owns the `deepseek` provider route; mounting a pi-ai profile with `provider: deepseek` in the same context throws `LlmError('DUPLICATE_ADAPTER')` by design.
 
 ## Config
 
@@ -12,12 +12,16 @@ A second, independent implementation of the same seam exists in `@deepseek-ai/ds
   config:
     apiKey: !!js process.env.DEEPSEEK_API_KEY    # or rely on the env fallback
     baseURL: !!js process.env.DEEPSEEK_BASE_URL  # default: https://api.deepseek.com
-    models: [deepseek-v4-flash, deepseek-v4-pro] # one adapter, registered for each name
     thinking: enabled        # optional; provider default is enabled
     reasoningEffort: high    # optional; high | max — omitted ⇒ not sent
+    models:                  # optional; defaults to V4 Flash and V4 Pro
+      - id: deepseek-v4-flash
+        name: DeepSeek V4 Flash
+      - id: private-reasoner
+        description: Company-hosted reasoning model
 ```
 
-`models` lists every model name this one adapter instance serves: the adapter registers itself for each (the harness model name IS the wire `model` string), so a `generate`/`stream` call routes to it whenever `options.model` is any of them. Registering a second adapter for a name already taken throws `LlmError('DUPLICATE_ADAPTER')` (the LLM service enforces one adapter per model, all-or-nothing).
+The plugin registers the single provider route `deepseek`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for clients such as ACP editors, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
 
 `reasoningEffort` is **omitted by default** — when unset, the `reasoning_effort` wire field is not sent and the server applies its own default for the model. The only accepted values are `high` and `max` (DeepSeek's official effort levels). It is meaningful only with thinking enabled (the provider default).
 

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

@@ -6,13 +6,23 @@
  */
 
 import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { serializeRequest } from './serialize.ts'
 import type { RequestDefaults } from './serialize.ts'
 import { parseSse } from './sse.ts'
 import { translate } from './translate.ts'
 import type { WireError } from './types.ts'
 
+/** One optional model entry advertised by the hand-written adapter. */
+export interface DeepSeekCatalogModel {
+  /** Wire model id accepted by the configured endpoint. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Optional selector detail for deployments with similar model variants. */
+  description?: string
+}
+
 /** 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. */
@@ -21,6 +31,8 @@ export interface DeepSeekAdapterOptions {
   baseURL: string
   /** Request defaults applied to every call (thinking mode, effort). */
   defaults?: RequestDefaults
+  /** Advisory models exposed to discovery consumers; requests remain unrestricted. */
+  models?: readonly DeepSeekCatalogModel[]
 }
 
 /**
@@ -49,6 +61,19 @@ export class DeepSeekAdapter extends LlmAdapter {
     super()
   }
 
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: 'DeepSeek' }
+  }
+
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve((this.options.models ?? []).map(model => ({
+      provider,
+      id: model.id,
+      name: model.name ?? model.id,
+      ...model.description === undefined ? {} : { description: model.description },
+    })))
+  }
+
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     const body = serializeRequest(options, this.options.defaults ?? {})
 

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

@@ -1,5 +1,5 @@
 /**
- * Register a {@link DeepSeekAdapter} for configured model names on `ctx.llm`. Configuration uses
+ * 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.
  * @module @deepseek-ai/dsh-llm-deepseek
@@ -9,9 +9,10 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-llm'
 import { DeepSeekAdapter } from './adapter.ts'
+import type { DeepSeekCatalogModel } from './adapter.ts'
 
 export { DeepSeekAdapter, httpErrorCode } from './adapter.ts'
-export type { DeepSeekAdapterOptions } from './adapter.ts'
+export type { DeepSeekAdapterOptions, DeepSeekCatalogModel } from './adapter.ts'
 export { serializeMessages, serializeRequest } from './serialize.ts'
 export type { RequestDefaults } from './serialize.ts'
 export { DONE, parseSse } from './sse.ts'
@@ -21,6 +22,11 @@ export type * from './types.ts'
 export const name = 'llm-deepseek'
 export const inject = ['llm']
 
+const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
+  { id: 'deepseek-v4-flash' },
+  { id: 'deepseek-v4-pro' },
+]
+
 /**
  * Plugin config, validated by the same-named schemastery schema. Every field
  * is optional in yml: credentials/endpoint fall back to the environment (a
@@ -32,40 +38,62 @@ export interface Config {
   apiKey?: string
   /** Endpoint base; falls back to $DEEPSEEK_BASE_URL, then the public API. */
   baseURL?: string
-  /** Model names to register (sent verbatim on the wire). */
-  models?: string[]
   /** Thinking-mode default for every request (provider default: enabled). */
   thinking?: 'enabled' | 'disabled'
   /** Thinking effort (only meaningful with thinking enabled). */
   reasoningEffort?: 'high' | 'max'
+  /** Advisory models shown by discovery consumers; defaults to V4 Flash and V4 Pro. */
+  models?: DeepSeekCatalogModel[]
 }
 
+const catalogModel: z<DeepSeekCatalogModel> = z.object({
+  id: z.string().required(),
+  name: z.string(),
+  description: z.string(),
+})
+
 export const Config: z<Config> = z.object({
   apiKey: z.string(),
   baseURL: z.string(),
-  models: z.array(z.string()).default(['deepseek-v4-flash', 'deepseek-v4-pro']),
   thinking: z.union(['enabled', 'disabled']),
   reasoningEffort: z.union(['high', 'max']),
+  models: z.array(catalogModel).default(DEFAULT_MODELS),
 })
 
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
 export const PUBLIC_BASE_URL = 'https://api.deepseek.com'
 
+/** Resolve, validate, and detach the advisory model catalog. */
+function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): DeepSeekCatalogModel[] {
+  const seen = new Set<string>()
+  return (models ?? DEFAULT_MODELS).map((model) => {
+    if (model.id.length === 0) throw new Error('llm-deepseek: catalog model ids must be non-empty')
+    if (model.name !== undefined && model.name.length === 0) {
+      throw new Error(`llm-deepseek: catalog model "${model.id}" has an empty name`)
+    }
+    if (seen.has(model.id)) throw new Error(`llm-deepseek: duplicate catalog model "${model.id}"`)
+    seen.add(model.id)
+    return {
+      id: model.id,
+      ...model.name === undefined ? {} : { name: model.name },
+      ...model.description === undefined ? {} : { description: model.description },
+    }
+  })
+}
+
 export function apply(ctx: Context, config: Config): void {
   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)')
   }
   const baseURL = config.baseURL ?? process.env.DEEPSEEK_BASE_URL ?? PUBLIC_BASE_URL
-  // schemastery's .default() guarantees models is set after validation.
-  const models = config.models as string[]
-
-  ctx.llm.registerAdapter(models, new DeepSeekAdapter({
+  ctx.llm.registerAdapter(['deepseek'], new DeepSeekAdapter({
     apiKey,
     baseURL,
     defaults: {
       thinking: config.thinking,
       reasoningEffort: config.reasoningEffort,
     },
+    models: resolveModels(config.models),
   }))
 }

packages/llm/llm-deepseek/tests/adapter.e2e.ts

@@ -16,11 +16,11 @@ const FLASH = 'deepseek-v4-flash'
 const PRO = 'deepseek-v4-pro'
 const contexts: Context[] = []
 
-async function harness(model: string, config: Partial<Config> = {}) {
+async function harness(_model: string, config: Partial<Config> = {}) {
   const ctx = new Context()
   contexts.push(ctx)
   await ctx.plugin(LlmService)
-  await ctx.plugin(LlmDeepSeek, { models: [model], ...config })
+  await ctx.plugin(LlmDeepSeek, config)
   return ctx
 }
 
@@ -134,6 +134,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', ()
     const ctx = await harness(FLASH, { thinking: 'disabled' })
     const kinds: string[] = []
     for await (const chunk of ctx.llm.stream({
+      provider: 'deepseek',
       model: FLASH,
       messages: ask('Count from 1 to 5, digits only.'),
       maxTokens: 50,

packages/llm/llm-deepseek/tests/adapter.spec.ts

@@ -86,7 +86,7 @@ const textEvents = [
 async function harness(baseURL: string, config: object = {}) {
   const ctx = new Context()
   await ctx.plugin(LlmService)
-  await ctx.plugin(LlmDeepSeek, { apiKey: 'test-key', baseURL, models: ['deepseek-v4-flash'], ...config })
+  await ctx.plugin(LlmDeepSeek, { apiKey: 'test-key', baseURL, ...config })
   return ctx
 }
 
@@ -123,6 +123,7 @@ describe('DeepSeekAdapter against a mock server', () => {
 
     const kinds: string[] = []
     for await (const chunk of ctx.llm.stream({
+      provider: 'deepseek',
       model: 'deepseek-v4-flash',
       messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
     })) {
@@ -193,7 +194,7 @@ describe('DeepSeekAdapter against a mock server', () => {
     )
     try {
       const iterate = async (): Promise<void> => {
-        for await (const _chunk of adapter.stream({ model: 'm', messages: [] })) { /* drain */ }
+        for await (const _chunk of adapter.stream({ provider: 'deepseek', model: 'm', messages: [] })) { /* drain */ }
       }
       await expect(iterate()).rejects.toThrow(/no response body/)
     } finally {
@@ -219,6 +220,7 @@ describe('DeepSeekAdapter against a mock server', () => {
     const pending = (async () => {
       const chunks = []
       for await (const chunk of ctx.llm.stream({
+        provider: 'deepseek',
         model: 'deepseek-v4-flash',
         messages: [],
         signal: controller.signal,
@@ -234,25 +236,81 @@ describe('DeepSeekAdapter against a mock server', () => {
 })
 
 describe('plugin registration and config', () => {
-  it('registers the configured models and unregisters on dispose (HMR safety)', async () => {
+  it('registers the deepseek provider and unregisters on dispose (HMR safety)', async () => {
     const server = await mockServer([])
     const ctx = new Context()
     await ctx.plugin(LlmService)
     const fiber = await ctx.plugin(LlmDeepSeek, {
       apiKey: 'k',
       baseURL: server.url,
-      models: ['deepseek-v4-flash', 'deepseek-v4-pro'],
     })
-    expect(ctx.llm.models().sort()).toEqual(['deepseek-v4-flash', 'deepseek-v4-pro'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
     await fiber.dispose()
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
-  it('defaults the model list', async () => {
+  it('owns the deepseek provider and advertises the default models', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
-    expect(ctx.llm.models().sort()).toEqual(['deepseek-v4-flash', 'deepseek-v4-pro'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
+      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
+      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+    ])
+  })
+
+  it('uses the default model catalog when apply is called directly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    LlmDeepSeek.apply(ctx, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
+      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
+      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+    ])
+  })
+
+  it('advertises configured models without restricting arbitrary request ids', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      models: [
+        { id: 'private-fast' },
+        { id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget' },
+      ],
+    })
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
+      { provider: 'deepseek', id: 'private-fast', name: 'private-fast' },
+      { provider: 'deepseek', id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget' },
+    ])
+  })
+
+  it('allows an explicit empty model catalog', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      models: [],
+    })
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([])
+  })
+
+  it.each([
+    [[{ id: '' }], /ids must be non-empty/],
+    [[{ id: 'm', name: '' }], /empty name/],
+    [[{ id: 'm' }, { id: 'm' }], /duplicate catalog model/],
+  ] as const)('rejects invalid advisory model config', async (models, message) => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await expect(ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      models: [...models],
+    })).rejects.toThrow(message)
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
   it('falls back to DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL env vars', async () => {
@@ -261,7 +319,7 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {})
-    expect(ctx.llm.models().length).toBeGreaterThan(0)
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
   })
 
   it('throws a clear error when no API key is available', async () => {
@@ -270,7 +328,7 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmService)
     await expect(ctx.plugin(LlmDeepSeek, {}))
       .rejects.toThrow(/an API key is required/)
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
   it('prefers explicit config over env for key and base URL', async () => {
@@ -287,7 +345,7 @@ describe('plugin registration and config', () => {
     vi.stubEnv('DEEPSEEK_BASE_URL', server.url)
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    await ctx.plugin(LlmDeepSeek, { apiKey: 'k', models: ['deepseek-v4-flash'] })
+    await ctx.plugin(LlmDeepSeek, { apiKey: 'k' })
     await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     expect(server.requests).toHaveLength(1)
   })
@@ -299,11 +357,12 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmService)
     // Registration succeeds; no call is made (would hit api.deepseek.com).
     await ctx.plugin(LlmDeepSeek, {})
-    expect(ctx.llm.models().length).toBeGreaterThan(0)
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
   })
 
-  it('adapter is constructible directly for embedding', () => {
+  it('adapter is constructible directly for embedding', async () => {
     const adapter = new DeepSeekAdapter({ apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
     expect(adapter).toBeInstanceOf(DeepSeekAdapter)
+    await expect(adapter.listModels('deepseek')).resolves.toEqual([])
   })
 })

packages/llm/llm-deepseek/tests/assemble.ts

@@ -15,11 +15,19 @@ export interface AssembledResult {
   finish: FinishReason
 }
 
-export async function assemble(ctx: Context, options: GenerateOptions): Promise<AssembledResult> {
+export async function assemble(ctx: Context, options: Omit<GenerateOptions, 'provider'> & { provider?: string }): Promise<AssembledResult> {
   const assembler = new BlockAssembler()
-  for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk)
+  const request = { provider: 'deepseek', ...options }
+  for await (const chunk of ctx.llm.stream(request)) assembler.push(chunk)
   return {
-    message: assembler.message(),
+    message: {
+      ...assembler.message(),
+      provenance: {
+        provider: request.provider,
+        model: request.model,
+        ...assembler.replayState === undefined ? {} : { replayState: assembler.replayState },
+      },
+    },
     ...assembler.usage !== undefined ? { usage: assembler.usage } : {},
     finish: assembler.finish,
   }

packages/llm/llm-deepseek/tests/serialize.spec.ts

@@ -4,7 +4,7 @@ import type { ContentBlock, GenerateOptions, Message } from '@deepseek-ai/dsh-ll
 import { serializeMessages, serializeRequest } from '@deepseek-ai/dsh-llm-deepseek'
 
 function request(overrides: Partial<GenerateOptions> = {}): GenerateOptions {
-  return { model: 'deepseek-v4-flash', messages: [], ...overrides }
+  return { provider: 'deepseek', model: 'deepseek-v4-flash', messages: [], ...overrides }
 }
 
 describe('serializeMessages', () => {