Merge remote-tracking branch 'origin/master' into mergebot/pr711

# Conflicts: # apps/cli/README.i18n.yaml # docs/module-graph.md # packages/client/connection/README.i18n.yaml # packages/client/runtime/README.i18n.yaml # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/src/api-proxy.ts
2026-07-31 02:02:47 +08:00
parent ecbd8babc1 47dafc28bc
commit 2e034bbbd3
455 changed files with 9824 additions and 1402 deletions
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -0,0 +1,441 @@
+/**
+ * Settings/credentials/llm RPC domains and their host-stream frames over
+ * createApiProxy: layered redacted describe, write-path rejection mapping,
+ * value-free credential views, the directory/live-route merge, and the three
+ * invalidation frames (settings/credentials/models changed).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import LlmService, { LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { Settings, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import { Credentials } from '@deepseek-ai/dsh-credentials'
+import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
+import type { HostFrame } from '../src/api/index.ts'
+import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
+import { RpcId } from '../src/api/rpc.ts'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const DEFAULTS = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
+}
+
+function expectOk<T>(response: RpcResponse<T>): T {
+  expect(response.result.ok).toBe(true)
+  if (!response.result.ok) throw new Error('unreachable')
+  return response.result.value
+}
+
+function expectErr<T>(response: RpcResponse<T>): { code: string; message: string; details: unknown } {
+  expect(response.result.ok).toBe(false)
+  if (response.result.ok) throw new Error('unreachable')
+  return response.result.error
+}
+
+/** In-memory settings provider: the seam base class owns all tested behavior. */
+class MemorySettings extends Settings {
+  doc: Record<string, unknown>
+
+  constructor(ctx: ConstructorParameters<typeof Settings>[0], options?: { doc?: Record<string, unknown>; readOnly?: boolean }) {
+    super(ctx)
+    this.doc = structuredClone(options?.doc ?? {})
+    this.readOnly = options?.readOnly ?? false
+  }
+
+  private readonly readOnly: boolean
+
+  get writable(): boolean {
+    return !this.readOnly
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    this.doc[ns] = structuredClone(section)
+    return Promise.resolve()
+  }
+}
+
+/** In-memory credential provider with an env-shadow double for the rejection path. */
+class MemoryCredentials extends Credentials {
+  private readonly values = new Map<string, string>()
+
+  constructor(ctx: ConstructorParameters<typeof Credentials>[0], options?: { shadowed?: string[] }) {
+    super(ctx)
+    this.shadowed = new Set(options?.shadowed ?? [])
+  }
+
+  private readonly shadowed: Set<string>
+
+  resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined> {
+    if (this.shadowed.has(ref)) return Promise.resolve({ value: 'from-env', source: 'env' })
+    const value = this.values.get(ref)
+    return Promise.resolve(value === undefined ? undefined : { value, source: 'file' })
+  }
+
+  describe(ref: CredentialRef): Promise<CredentialInfo> {
+    if (this.shadowed.has(ref)) return Promise.resolve({ configured: true, source: 'env', writable: false })
+    const configured = this.values.has(ref)
+    return Promise.resolve({ configured, ...configured ? { source: 'file' } : {}, writable: true })
+  }
+
+  set(ref: CredentialRef, value: string): Promise<void> {
+    if (this.shadowed.has(ref)) {
+      return Promise.reject(new Error(`credentials: ${ref} is shadowed by the read-only environment`))
+    }
+    this.values.set(ref, value)
+    this.ctx.emit('credentials/updated', ref)
+    return Promise.resolve()
+  }
+
+  unset(ref: CredentialRef): Promise<void> {
+    if (this.shadowed.has(ref)) {
+      return Promise.reject(new Error(`credentials: ${ref} is shadowed by the read-only environment`))
+    }
+    this.values.delete(ref)
+    this.ctx.emit('credentials/updated', ref)
+    return Promise.resolve()
+  }
+}
+
+/** Catalog-serving adapter stub for the llm.models path. */
+class CatalogAdapter extends LlmAdapter {
+  constructor(private readonly name: string, private readonly models: readonly string[]) {
+    super()
+  }
+
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: this.name }
+  }
+
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve(this.models.map(id => ({ provider, id, name: id })))
+  }
+
+
+  async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    throw new Error('not exercised')
+  }
+}
+
+class BrokenCatalogAdapter extends CatalogAdapter {
+  override listModels(): Promise<readonly LlmModelInfo[]> {
+    return Promise.reject(new Error('catalog backend down'))
+  }
+}
+
+const NS = settingsNamespace('llm-deepseek')
+
+const AdapterConfig = z.object({
+  apiKey: z.string().role('secret'),
+  apiKeyEnv: z.string().default('DEEPSEEK_API_KEY'),
+  baseURL: z.string(),
+})
+
+async function harness(options?: {
+  settings?: false | { doc?: Record<string, unknown>; readOnly?: boolean }
+  credentials?: false | { shadowed?: string[] }
+  /** Skip the directory registration to exercise a namespace the proxy does not expose. */
+  configurableProviders?: false
+}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LlmService)
+  if (options?.settings !== false) await ctx.plugin(MemorySettings, options?.settings)
+  if (options?.credentials !== false) await ctx.plugin(MemoryCredentials, options?.credentials)
+  // The proxy serves only namespaces a configurable provider addresses, which
+  // is what the real LLM plugins declare at load; the tests mirror that.
+  if (options?.configurableProviders !== false) {
+    ctx.llm.registerConfigurableProviders([
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] },
+    ])
+  }
+  // Host-stream opener reads the committed-workspace baseline; the stub
+  // suffices — the real workspace composition is api-proxy-workspace.spec's.
+  ctx.provide('workspace', { list: () => [] } as never)
+  return ctx
+}
+
+/** Drain `count` host frames matching `types`, then abort the stream. */
+async function collectHost(
+  api: ReturnType<typeof createApiProxy>,
+  types: string[],
+  count: number,
+  run: () => Promise<void>,
+): Promise<HostFrame[]> {
+  const abort = new AbortController()
+  const frames: HostFrame[] = []
+  const stream = api.events.host(request({}), abort.signal)
+  const consume = (async () => {
+    for await (const frame of stream) {
+      if (!types.includes(frame.payload.type)) continue
+      frames.push(frame.payload)
+      if (frames.length >= count) abort.abort()
+    }
+  })()
+  await run()
+  await consume
+  return frames
+}
+
+describe('settings domain', () => {
+  it('reports an actionable error when no settings provider is mounted', async () => {
+    const ctx = await harness({ settings: false })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.settings.describe(request({})))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('dsh-settings-local')
+  })
+
+  it('describes layered redacted namespaces with their secret slots', async () => {
+    const ctx = await harness({ settings: { doc: { 'llm-deepseek': { apiKey: 'user-secret', baseURL: 'https://user' } } } })
+    ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.settings.describe(request({})))
+    expect(value.writable).toBe(true)
+    expect(value.namespaces).toHaveLength(1)
+    const view = value.namespaces[0]!
+    expect(view.ns).toBe('llm-deepseek')
+    expect(view.applies).toBe('live')
+    expect((view.schema as { refs?: unknown }).refs).toBeDefined()
+    expect(view.value).toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://user' })
+    expect(view.base).toEqual({ baseURL: 'https://base' })
+    expect(view.user).toEqual({ baseURL: 'https://user' })
+    expect(view.secrets).toEqual([{ path: ['apiKey'], set: true }])
+    expect(JSON.stringify(value)).not.toContain('user-secret')
+  })
+
+  it('serves only namespaces a registered model provider addresses', async () => {
+    // The settings seam is general: any plugin may register a namespace for
+    // its own configuration. The Web configuration plane is not — it is the
+    // model-provider surface, and a namespace nothing in the provider
+    // directory addresses must be invisible and unwritable here, so a future
+    // plugin cannot become remotely configurable just by registering.
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    ctx.settings.register(settingsNamespace('some-other-plugin'), z.object({ secretPath: z.string() }))
+    const api = createApiProxy(ctx, DEFAULTS)
+
+    const value = expectOk(await api.settings.describe(request({})))
+    expect(value.namespaces.map(view => view.ns)).toEqual(['llm-deepseek'])
+
+    for (const response of [
+      await api.settings.update(request({ ns: 'some-other-plugin', patch: { secretPath: '/etc/shadow' } })),
+      await api.settings.replace(request({ ns: 'some-other-plugin', section: {} })),
+    ]) {
+      const error = expectErr(response)
+      expect(error.code).toBe('settings-not-exposed')
+      expect(error.details).toEqual({ ns: 'some-other-plugin' })
+    }
+    // The write never reached the seam.
+    expect(ctx.settings.describe().find(d => String(d.ns) === 'some-other-plugin')?.value).toEqual({})
+  })
+
+  it('refuses even a model-provider namespace once its directory entry is gone', async () => {
+    const ctx = await harness({ configurableProviders: false })
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    expect(expectOk(await api.settings.describe(request({}))).namespaces).toEqual([])
+    expect(expectErr(await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://x' } }))).code)
+      .toBe('settings-not-exposed')
+  })
+
+  it('invalidates the model catalog when a provider namespace changes, and broadcasts a raw-only change', async () => {
+    // Editing `models` changes no route, so llm/adapters-updated never fires
+    // and an open model picker kept serving the old catalog. And storing an
+    // override equal to the resolved value emits nothing on settings/updated,
+    // so another tab never learned the field became overridden.
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const frames = await collectHost(api, ['host/settings-changed', 'host/models-changed'], 2, async () => {
+      await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://base' } }))
+    })
+    expect(frames).toEqual([
+      { type: 'host/settings-changed', ns: 'llm-deepseek' },
+      { type: 'host/models-changed' },
+    ])
+    // The resolved value never moved: base already said https://base.
+    expect(expectOk(await api.settings.describe(request({}))).namespaces[0]!.value)
+      .toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://base' })
+  })
+
+  it('maps a stale expectedRevision to settings-conflict carrying both revisions', async () => {
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const opened = expectOk(await api.settings.describe(request({}))).namespaces[0]!.revision
+    expect(expectOk(await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://first' }, expectedRevision: opened })))
+      .revision).toBe(opened + 1)
+    const error = expectErr(await api.settings.update(request({ ns: 'llm-deepseek', patch: { baseURL: 'https://second' }, expectedRevision: opened })))
+    expect(error.code).toBe('settings-conflict')
+    expect(error.details).toEqual({ ns: 'llm-deepseek', expected: opened, actual: opened + 1 })
+    // The refused write changed nothing.
+    expect(expectOk(await api.settings.describe(request({}))).namespaces[0]!.user).toEqual({ baseURL: 'https://first' })
+  })
+
+  it('updates the user layer, answers with the new redacted view, and broadcasts the frame', async () => {
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const frames = await collectHost(api, ['host/settings-changed'], 1, async () => {
+      const view = expectOk(await api.settings.update(request({ ns: 'llm-deepseek', patch: { apiKey: 'sk-new', baseURL: 'https://next' } })))
+      expect(view.value).toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://next' })
+      expect(view.user).toEqual({ baseURL: 'https://next' })
+      expect(view.secrets).toEqual([{ path: ['apiKey'], set: true }])
+      expect(JSON.stringify(view)).not.toContain('sk-new')
+    })
+    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'llm-deepseek' }])
+  })
+
+  it('replace resets the user layer wholesale', async () => {
+    const ctx = await harness({ settings: { doc: { 'llm-deepseek': { baseURL: 'https://user' } } } })
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const view = expectOk(await api.settings.replace(request({ ns: 'llm-deepseek', section: {} })))
+    expect(view.value).toEqual({ apiKeyEnv: 'DEEPSEEK_API_KEY' })
+    expect(view.user).toEqual({})
+  })
+
+  it.each([
+    ['an invalid namespace name', 'Not A Namespace', {}],
+    ['a schema-invalid patch', 'llm-deepseek', { baseURL: 42 }],
+  ])('rejects %s as settings-rejected', async (_case, ns, patch) => {
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.settings.update(request({ ns, patch })))
+    expect(error.code).toBe('settings-rejected')
+    expect(error.details).toEqual({ ns })
+  })
+
+  it('answers an unregistered namespace exactly like an unexposed one', async () => {
+    // Deliberately indistinguishable: separating "does not exist" from
+    // "exists but is not yours to configure" would let a caller enumerate the
+    // registered namespaces one probe at a time.
+    const ctx = await harness()
+    ctx.settings.register(NS, AdapterConfig)
+    ctx.settings.register(settingsNamespace('some-other-plugin'), z.object({ secretPath: z.string() }))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const unknown = expectErr(await api.settings.update(request({ ns: 'unknown-ns', patch: {} })))
+    const unexposed = expectErr(await api.settings.update(request({ ns: 'some-other-plugin', patch: {} })))
+    expect(unknown.code).toBe('settings-not-exposed')
+    expect(unexposed.code).toBe(unknown.code)
+    expect(unexposed.message.replace('some-other-plugin', 'unknown-ns')).toBe(unknown.message)
+  })
+
+  it('maps a read-only provider refusal onto the same rejection', async () => {
+    const ctx = await harness({ settings: { readOnly: true } })
+    ctx.settings.register(NS, AdapterConfig)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.settings.describe(request({})))
+    expect(value.writable).toBe(false)
+    const error = expectErr(await api.settings.update(request({ ns: 'llm-deepseek', patch: {} })))
+    expect(error.code).toBe('settings-rejected')
+    expect(error.message).toContain('read-only')
+  })
+})
+
+describe('credentials domain', () => {
+  it('reports an actionable error when no credential provider is mounted', async () => {
+    const ctx = await harness({ credentials: false })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.credentials.describe(request({ refs: ['A'] })))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('dsh-credentials-local')
+  })
+
+  it('describes value-free views and flips state through set/unset with frames', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const before = expectOk(await api.credentials.describe(request({ refs: ['OPENAI_API_KEY'] })))
+    expect(before.credentials).toEqual({ OPENAI_API_KEY: { configured: false, writable: true } })
+    const frames = await collectHost(api, ['host/credentials-changed'], 2, async () => {
+      expectOk(await api.credentials.set(request({ ref: 'OPENAI_API_KEY', value: 'sk-secret' })))
+      const after = expectOk(await api.credentials.describe(request({ refs: ['OPENAI_API_KEY'] })))
+      expect(after.credentials).toEqual({ OPENAI_API_KEY: { configured: true, source: 'file', writable: true } })
+      expect(JSON.stringify(after)).not.toContain('sk-secret')
+      expectOk(await api.credentials.unset(request({ ref: 'OPENAI_API_KEY' })))
+    })
+    expect(frames).toEqual([
+      { type: 'host/credentials-changed', ref: 'OPENAI_API_KEY' },
+      { type: 'host/credentials-changed', ref: 'OPENAI_API_KEY' },
+    ])
+  })
+
+  it('maps a shadowed write onto credential-rejected for set and unset alike', async () => {
+    const ctx = await harness({ credentials: { shadowed: ['DEEPSEEK_API_KEY'] } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const described = expectOk(await api.credentials.describe(request({ refs: ['DEEPSEEK_API_KEY'] })))
+    expect(described.credentials['DEEPSEEK_API_KEY']).toEqual({ configured: true, source: 'env', writable: false })
+    const setError = expectErr(await api.credentials.set(request({ ref: 'DEEPSEEK_API_KEY', value: 'x' })))
+    expect(setError.code).toBe('credential-rejected')
+    expect(setError.details).toEqual({ ref: 'DEEPSEEK_API_KEY' })
+    const unsetError = expectErr(await api.credentials.unset(request({ ref: 'DEEPSEEK_API_KEY' })))
+    expect(unsetError.code).toBe('credential-rejected')
+  })
+})
+
+describe('llm domain', () => {
+  it('merges the configurable directory with live routes and appends undeclared ones', async () => {
+    const ctx = await harness({ configurableProviders: false })
+    ctx.llm.registerConfigurableProviders([
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] },
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    ])
+    ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', ['deepseek-v4-flash']))
+    ctx.llm.registerAdapter(['undeclared'], new CatalogAdapter('Undeclared', ['u-1']))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.llm.providers(request({})))
+    expect(value.providers).toEqual([
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: false },
+      { provider: 'undeclared', displayName: 'Undeclared', settingsNs: '', settingsPath: [], active: true },
+    ])
+  })
+
+  it('serves the host-scoped catalog with per-provider failures contained', async () => {
+    const ctx = await harness()
+    ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', ['deepseek-v4-flash', 'deepseek-v4-pro']))
+    ctx.llm.registerAdapter(['broken'], new BrokenCatalogAdapter('Broken', []))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const value = expectOk(await api.llm.models(request({})))
+    expect(value.groups).toEqual([{
+      id: 'deepseek-official',
+      name: 'DeepSeek',
+      models: [
+        { id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
+        { id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+      ],
+    }])
+    expect(value.failures).toEqual([{ id: 'broken', name: 'Broken', message: 'catalog backend down' }])
+  })
+
+  it('broadcasts host/models-changed at every topology commit point', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const frames = await collectHost(api, ['host/models-changed'], 2, async () => {
+      const dispose = ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', []))
+      dispose()
+      return Promise.resolve()
+    })
+    expect(frames).toEqual([{ type: 'host/models-changed' }, { type: 'host/models-changed' }])
+  })
+})
--- a/packages/host/apiproxy/tests/api-proxy-models.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
@@ -85,9 +85,9 @@ async function harness(logged?: {
  await ctx.plugin(LlmService)
  await ctx.plugin(UserInteractionService)
  await ctx.plugin(AgentRegistry)
-  ctx.llm.registerAdapter(['deepseek'], new CatalogAdapter('DeepSeek', [
-    { provider: 'deepseek', id: 'deepseek-chat', name: 'DeepSeek Chat' },
-    { provider: 'deepseek', id: 'deepseek-reasoner', name: 'DeepSeek Reasoner', description: 'Reasoning model' },
+  ctx.llm.registerAdapter(['deepseek-official'], new CatalogAdapter('DeepSeek', [
+    { provider: 'deepseek-official', id: 'deepseek-chat', name: 'DeepSeek Chat' },
+    { provider: 'deepseek-official', id: 'deepseek-reasoner', name: 'DeepSeek Reasoner', description: 'Reasoning model' },
  ], REASONING))
  ctx.llm.registerAdapter(['broken'], new CatalogAdapter('Broken Provider', new Error('catalog offline')))
  ctx.llm.registerAdapter(['metadata-broken'], new CatalogAdapter('Metadata Broken', [
@@ -120,20 +120,20 @@ function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false
 describe('Web session model selection', () => {
  it('groups successful providers, isolates failures, and preserves an unlisted current model', async () => {
    const { ctx, sessionId } = await harness({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'private-preview',
      reasoningEffort: ReasoningEffortId('max'),
    })
-    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })

    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
    expect(catalog.current).toEqual({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'private-preview',
      reasoningEffort: 'max',
    })
    expect(catalog.groups).toEqual([{
-      id: 'deepseek',
+      id: 'deepseek-official',
      name: 'DeepSeek',
      models: [
        { id: 'deepseek-chat', name: 'DeepSeek Chat', reasoning: REASONING },
@@ -165,43 +165,43 @@ describe('Web session model selection', () => {

  it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
    const { ctx, agent, sessionId } = await harness()
-    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
    const signal = new AbortController().signal

    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
-      .toEqual({ provider: 'deepseek', model: 'deepseek-chat' })
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat' })
    expect((await ctx.systemPrompt.assemble()).variables)
-      .toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+      .toMatchObject({ provider: 'deepseek-official', model: 'deepseek-chat' })

    const selected = expectValue(await api.sessions.selectModel(request({
      sessionId,
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'private-preview',
      reasoningEffort: 'max',
    })))
    expect(selected.selected).toEqual({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'private-preview',
      reasoningEffort: 'max',
    })
    await expect(agentEvents(ctx, agent).waterfall(
      'agent/request', 1, 0, signal, () => Promise.resolve(seed),
-    )).resolves.toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+    )).resolves.toMatchObject({ provider: 'deepseek-official', model: 'deepseek-chat' })

    expect((await ctx.systemPrompt.assemble()).variables)
-      .toMatchObject({ provider: 'deepseek', model: 'private-preview' })
+      .toMatchObject({ provider: 'deepseek-official', model: 'private-preview' })
    await expect(agentEvents(ctx, agent).waterfall(
      'agent/request', 1, 1, signal, () => Promise.resolve(seed),
    )).resolves.toMatchObject({
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'private-preview',
      reasoningEffort: 'max',
    })

    const unsupported = await api.sessions.selectModel(request({
      sessionId,
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'private-preview',
      reasoningEffort: 'medium',
    }))
@@ -209,7 +209,7 @@ describe('Web session model selection', () => {
      ok: false,
      error: {
        code: 'model-unavailable',
-        message: 'provider "deepseek" model "private-preview" does not support reasoning effort "medium"',
+        message: 'provider "deepseek-official" model "private-preview" does not support reasoning effort "medium"',
      },
    })

@@ -227,7 +227,7 @@ describe('Web session model selection', () => {
      },
    })
    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
-      .toEqual({ provider: 'deepseek', model: 'private-preview', reasoningEffort: 'max' })
+      .toEqual({ provider: 'deepseek-official', model: 'private-preview', reasoningEffort: 'max' })
    await ctx.fiber.dispose()
  })
 })
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -24,6 +24,9 @@ function scriptedApi(overrides: {
  skills?: Partial<ApiProxy['skills']>
  events?: Partial<ApiProxy['events']>
  goals?: Partial<ApiProxy['goals']>
+  settings?: Partial<ApiProxy['settings']>
+  credentials?: Partial<ApiProxy['credentials']>
+  llm?: Partial<ApiProxy['llm']>
  respond?: ApiProxy['respond']
 } = {}): ApiProxy {
  async function *empty<F>(): AsyncGenerator<RpcRequest<F>> { /* no frames */ }
@@ -37,10 +40,10 @@ function scriptedApi(overrides: {
      history: r => ok(r, {
        events: [],
        hasMore: false,
-        modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+        modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
      }),
      models: r => ok(r, {
-        current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+        current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
        groups: [],
        failures: [],
      }),
@@ -84,6 +87,24 @@ function scriptedApi(overrides: {
      clear: err,
      ...overrides.goals,
    },
+    settings: {
+      describe: r => ok(r, { writable: true, namespaces: [] }),
+      update: err,
+      replace: err,
+      mutate: err,
+      ...overrides.settings,
+    },
+    credentials: {
+      describe: r => ok(r, { credentials: {} }),
+      set: err,
+      unset: err,
+      ...overrides.credentials,
+    },
+    llm: {
+      providers: r => ok(r, { providers: [] }),
+      models: r => ok(r, { groups: [], failures: [] }),
+      ...overrides.llm,
+    },
    events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
    respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
  }
@@ -93,6 +114,15 @@ function client(api: ApiProxy, timeoutMs?: number): InProcessApiClient {
  return new InProcessApiClient(toFetchHandler(api), timeoutMs)
 }

+/** Wrap one scripted method to record its invocation into `seen` before responding. */
+function recorderInto(seen: { method: string; payload: unknown }[]) {
+  return <P, V>(method: string, respond: (r: RpcRequest<P>) => Promise<RpcResponse<V>>) =>
+    (r: RpcRequest<P>): Promise<RpcResponse<V>> => {
+      seen.push({ method, payload: r.payload })
+      return respond(r)
+    }
+}
+
 describe('unary round trip', () => {
  it('carries payload out and value back through the full wire form', async () => {
    let seen: RpcRequest<{ cursor?: string }> | undefined
@@ -501,11 +531,7 @@ describe('goals unary surface', () => {

  it('round-trips every goal method with its own payload and value shape', async () => {
    const seen: { method: string; payload: unknown }[] = []
-    const record = <P, V>(method: string, respond: (r: RpcRequest<P>) => Promise<RpcResponse<V>>) =>
-      (r: RpcRequest<P>): Promise<RpcResponse<V>> => {
-        seen.push({ method, payload: r.payload })
-        return respond(r)
-      }
+    const record = recorderInto(seen)
    const api = scriptedApi({
      goals: {
        create: record('goal.create', r => ok(r, ack)),
@@ -619,3 +645,84 @@ describe('envelope tap', () => {
    expect(batches).toEqual([])
  })
 })
+
+describe('config unary surface', () => {
+  it('round-trips every settings/credentials/llm method with its own payload and value shape', async () => {
+    const seen: { method: string; payload: unknown }[] = []
+    const record = recorderInto(seen)
+    const view = {
+      ns: 'llm-deepseek',
+      schema: { uid: 1, refs: { 1: { type: 'object' } } },
+      value: { baseURL: 'https://next' },
+      user: { baseURL: 'https://next' },
+      applies: 'live' as const,
+      secrets: [{ path: ['apiKey'], set: true }],
+      revision: 0,
+    }
+    const providerRow = {
+      provider: 'openai',
+      displayName: 'openai',
+      settingsNs: 'llm-pi-ai',
+      settingsPath: ['providers', 'openai'],
+      active: false,
+    }
+    const group = { id: 'deepseek-official', name: 'DeepSeek', models: [{ id: 'deepseek-v4-flash', name: 'Flash' }] }
+    const api = scriptedApi({
+      settings: {
+        describe: record('settings.describe', r => ok(r, { writable: true, namespaces: [view] })),
+        update: record('settings.update', r => ok(r, view)),
+        replace: record('settings.replace', r => ok(r, view)),
+        mutate: record('settings.mutate', r => ok(r, view)),
+      },
+      credentials: {
+        describe: record('credentials.describe', r => ok(r, { credentials: { OPENAI_API_KEY: { configured: true, source: 'file', writable: true } } })),
+        set: record('credentials.set', r => ok(r, {})),
+        unset: record('credentials.unset', r => ok(r, {})),
+      },
+      llm: {
+        providers: record('llm.providers', r => ok(r, { providers: [providerRow] })),
+        models: record('llm.models', r => ok(r, { groups: [group], failures: [] })),
+      },
+    })
+    const c = client(api)
+
+    const described = await c.settings.describe({})
+    expect(described.result).toEqual({ ok: true, value: { writable: true, namespaces: [view] } })
+    const updated = await c.settings.update({ ns: 'llm-deepseek', patch: { baseURL: 'https://next' } })
+    expect(updated.result).toEqual({ ok: true, value: view })
+    const replaced = await c.settings.replace({ ns: 'llm-deepseek', section: {} })
+    expect(replaced.result).toEqual({ ok: true, value: view })
+    const mutated = await c.settings.mutate({
+      ns: 'llm-deepseek',
+      ops: [{ op: 'unset', path: ['baseURL'] }],
+      expectedRevision: 0,
+    })
+    expect(mutated.result).toEqual({ ok: true, value: view })
+    const creds = await c.credentials.describe({ refs: ['OPENAI_API_KEY'] })
+    expect(creds.result).toEqual({ ok: true, value: { credentials: { OPENAI_API_KEY: { configured: true, source: 'file', writable: true } } } })
+    expect((await c.credentials.set({ ref: 'OPENAI_API_KEY', value: 'sk-x' })).result).toEqual({ ok: true, value: {} })
+    expect((await c.credentials.unset({ ref: 'OPENAI_API_KEY' })).result).toEqual({ ok: true, value: {} })
+    const providers = await c.llm.providers({})
+    expect(providers.result).toEqual({ ok: true, value: { providers: [providerRow] } })
+    const models = await c.llm.models({})
+    expect(models.result).toEqual({ ok: true, value: { groups: [group], failures: [] } })
+
+    expect(seen.map(call => call.method)).toEqual([
+      'settings.describe', 'settings.update', 'settings.replace', 'settings.mutate',
+      'credentials.describe', 'credentials.set', 'credentials.unset',
+      'llm.providers', 'llm.models',
+    ])
+    expect(seen[1]?.payload).toEqual({ ns: 'llm-deepseek', patch: { baseURL: 'https://next' } })
+    expect(seen[3]?.payload)
+      .toEqual({ ns: 'llm-deepseek', ops: [{ op: 'unset', path: ['baseURL'] }], expectedRevision: 0 })
+    expect(seen[5]?.payload).toEqual({ ref: 'OPENAI_API_KEY', value: 'sk-x' })
+  })
+
+  it('rejects an invalid credential reference name at the carrier boundary', async () => {
+    const api = scriptedApi()
+    const response = await client(api).credentials.set({ ref: 'not a var', value: 'x' })
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('bad-request')
+  })
+})
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -63,7 +63,7 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
          result: {
            ok: true,
            value: {
-              current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+              current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
              groups: [],
              failures: [],
            },
@@ -190,6 +190,39 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'internal', message: 'stub', details: {} } } }
      },
    },
+    settings: {
+      async describe(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { writable: true, namespaces: [] } } }
+      },
+      async update(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'settings-rejected', message: 'stub', details: { ns: request.payload.ns } } } }
+      },
+      async replace(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'settings-rejected', message: 'stub', details: { ns: request.payload.ns } } } }
+      },
+      async mutate(request) {
+        return { rpcId: request.rpcId, result: { ok: false, error: { code: 'settings-rejected', message: 'stub', details: { ns: request.payload.ns } } } }
+      },
+    },
+    credentials: {
+      async describe(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { credentials: {} } } }
+      },
+      async set(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: {} } }
+      },
+      async unset(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: {} } }
+      },
+    },
+    llm: {
+      async providers(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { providers: [] } } }
+      },
+      async models(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { groups: [], failures: [] } } }
+      },
+    },
    events: {
      mux: (_request, signal) => stream(muxFrames, signal),
      host: (_request, signal) => stream(hostFrames, signal),
@@ -243,7 +276,7 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
    expect((await c.sessions.models({ sessionId: 's' as never })).result.ok).toBe(true)
    const selected = await c.sessions.selectModel({
      sessionId: 's' as never,
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'deepseek-v4-flash',
      reasoningEffort: 'max',
    })
@@ -251,7 +284,7 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
      ok: true,
      value: {
        selected: {
-          provider: 'deepseek',
+          provider: 'deepseek-official',
          model: 'deepseek-v4-flash',
          reasoningEffort: 'max',
        },
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -191,13 +191,13 @@ describe('sessions domain schemas', () => {
    expect(sessionHistoryValueSchema.parse({
      events: [],
      hasMore: false,
-      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
    }).hasMore).toBe(false)
    expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
    expect(sessionModelsValueSchema.parse({
-      current: { provider: 'deepseek', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
+      current: { provider: 'deepseek-official', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
      groups: [{
-        id: 'deepseek',
+        id: 'deepseek-official',
        name: 'DeepSeek',
        models: [{
          id: 'deepseek-v4-flash',
@@ -217,12 +217,12 @@ describe('sessions domain schemas', () => {
    }).groups[0]?.models[0]?.id).toBe('deepseek-v4-flash')
    expect(sessionSelectModelRequestSchema.parse({
      sessionId: 's1',
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'deepseek-v4-pro',
      reasoningEffort: 'max',
    }).reasoningEffort).toBe('max')
    expect(sessionSelectModelValueSchema.parse({
-      selected: { provider: 'deepseek', model: 'deepseek-v4-pro', reasoningEffort: 'max' },
+      selected: { provider: 'deepseek-official', model: 'deepseek-v4-pro', reasoningEffort: 'max' },
    }).selected.reasoningEffort).toBe('max')
    expect(() => sessionSelectModelRequestSchema.parse({
      sessionId: 's1',
@@ -231,14 +231,14 @@ describe('sessions domain schemas', () => {
    })).toThrow()
    expect(() => sessionSelectModelRequestSchema.parse({
      sessionId: 's1',
-      provider: 'deepseek',
+      provider: 'deepseek-official',
      model: 'm',
      reasoningEffort: '',
    })).toThrow()
    expect(() => sessionModelsValueSchema.parse({
-      current: { provider: 'deepseek', model: 'm' },
+      current: { provider: 'deepseek-official', model: 'm' },
      groups: [{
-        id: 'deepseek',
+        id: 'deepseek-official',
        name: 'DeepSeek',
        models: [{ id: 'm', name: 'M', reasoning: { efforts: [] } }],
      }],