feat(web): add session model selector

packages/host/runtime/README.md

@@ -20,6 +20,8 @@ Which plugins mount and with what defaults is decided only here — shells must
 
 Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session and every still-pending question with its original rpcId. Question responses, including blank per-item answers, are validated against the owning session and exact request before an atomic first-wins claim; answer, whole-request cancellation, owner abort, and provider disposal broadcast `question/resolved`. The host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
 
+The Web front door installs the shared `installAgentLlmTarget` coupling for every created or resumed agent. A session starts from the latest logged `request/header` route when one exists, otherwise from the Host default. `session.models` discovers every registered provider concurrently, keeps successful groups when another provider fails, and inserts the current target as an unlisted row when its provider omits it. A selection changes the mutable session target immediately; prompt assembly snapshots it atomically with request routing, so a change during a running step first applies to the next assembled step.
+
 ## Model Experience
 
 Indirectly, through the non-blocking first-message title request owned by [`dsh-session-title-llm`](../../session-title/session-title-llm/README.md) when `sessionTitleLlm` is enabled, the provider/model defaults injected into created and resumed agents, the other model-facing plugins `bootHost` mounts, and the logged [workspace-instruction prefix](../../context/workspace-context/README.md#prompt-shape) when `workspaceContext` is enabled.

packages/host/runtime/src/api-proxy.ts

@@ -6,13 +6,15 @@
 import { randomUUID } from 'node:crypto'
 import { stat } from 'node:fs/promises'
 import type { Context } from 'cordis'
-import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentLlmTargetRef, AgentStatus } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
 import type {
-  ApiProxy, HistoryEntry, HostFrame, MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
+  ApiProxy, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup, ModelTarget,
+  MuxFrame, QuestionResponsePayload, SessionSummary, ToolEventView,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { questionResponsePayloadSchema } from '@deepseek-ai/dsh-host-apiproxy/api/questions.schema'
 import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -280,11 +282,36 @@ class SessionNotFound extends Error {}
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
   const agentOptions = { provider: defaults.provider, model: defaults.model }
+  type WebLlmTargetRef = AgentLlmTargetRef & { current: ModelTarget }
+  const targets = new WeakMap<Agent, WebLlmTargetRef>()
   /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
   const resumes = new Map<SessionId, Promise<Agent>>()
   const pendingQuestions = new Map<RpcId, PendingQuestion>()
   const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
 
+  /** Install or return the session-local target that prompt assembly snapshots. */
+  function targetFor(agent: Agent): WebLlmTargetRef {
+    const installed = targets.get(agent)
+    if (installed !== undefined) return installed
+    const logged = agent.session.requestHeader()?.config
+    const target: WebLlmTargetRef = {
+      current: logged === undefined
+        ? { provider: defaults.provider, model: defaults.model }
+        : { provider: logged.provider, model: logged.model },
+      assembled: undefined,
+    }
+    installAgentLlmTarget(agent.ctx, target)
+    targets.set(agent, target)
+    return target
+  }
+
+  /** Pre-publication setup used by both fresh and resumed Web agents. */
+  function installTarget(agentCtx: Context): void {
+    const agent = agentCtx.agent
+    if (agent === undefined) throw new Error('api-proxy: agent setup has no scoped agent')
+    targetFor(agent)
+  }
+
   /** Send one transient frame to every connected mux consumer. */
   function broadcast(payload: MuxFrame): void {
     const envelope = frame(payload)
@@ -363,7 +390,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       resume = (async () => {
         try {
           await assertServable(sessionId)
-          const handle = await ctx.agents.resume({ resumeSessionId: sessionId, agentOptions })
+          const handle = await ctx.agents.resume({
+            resumeSessionId: sessionId,
+            agentOptions,
+            setup: installTarget,
+          })
           return handle.agent
         } finally {
           resumes.delete(sessionId)
@@ -409,7 +440,12 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         // one, the default project is the host-level default (the host process
         // working directory unless boot overrides it).
         const cwd = request.payload.cwd ?? defaults.cwd
-        const handle = await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })
+        const handle = await ctx.agents.create({
+          sessionId,
+          agentOptions,
+          meta: { cwd },
+          setup: installTarget,
+        })
         return ok(request, { sessionId: handle.agent.id })
       },
 
@@ -425,7 +461,71 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
           return { event, ...view === undefined ? {} : { view } }
         })
-        return ok(request, { events: entries, hasMore: page.hasMore })
+        const current = targetFor(found.agent).current
+        return ok(request, { events: entries, hasMore: page.hasMore, modelTarget: { ...current } })
+      },
+
+      async models(request) {
+        const { sessionId } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const current = targetFor(found.agent).current
+        const catalog = await Promise.all(ctx.llm.listProviders().map(async (provider) => {
+          try {
+            const models = await ctx.llm.listModels(provider.id)
+            const group: ModelProviderGroup = {
+              id: provider.id,
+              name: provider.name,
+              models: models.map(model => ({
+                id: model.id,
+                name: model.name,
+                ...model.description === undefined ? {} : { description: model.description },
+              })),
+            }
+            return { kind: 'group' as const, group }
+          } catch (error: unknown) {
+            const failure: ModelCatalogFailure = {
+              id: provider.id,
+              name: provider.name,
+              message: error instanceof Error ? error.message : String(error),
+            }
+            return { kind: 'failure' as const, failure }
+          }
+        }))
+        const groups = catalog.flatMap(item => item.kind === 'group' ? [item.group] : [])
+        const failures = catalog.flatMap(item => item.kind === 'failure' ? [item.failure] : [])
+        const currentGroup = groups.find(group => group.id === current.provider)
+        if (
+          currentGroup !== undefined
+          && !currentGroup.models.some(model => model.id === current.model)
+        ) {
+          currentGroup.models.push({
+            id: current.model,
+            name: current.model,
+            unlisted: true,
+          })
+        }
+        return ok(request, {
+          current: { ...current },
+          groups: groups.filter(group => group.models.length > 0),
+          failures,
+        })
+      },
+
+      async selectModel(request) {
+        const { sessionId, provider, model } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        if (!ctx.llm.listProviders().some(entry => entry.id === provider)) {
+          return err(request, {
+            code: 'model-unavailable',
+            message: `provider "${provider}" is not registered`,
+            details: { provider, model },
+          })
+        }
+        const selected: ModelTarget = { provider, model }
+        targetFor(found.agent).current = selected
+        return ok(request, { selected: { ...selected } })
       },
 
       async prompt(request) {

packages/host/runtime/tests/api-proxy-models.spec.ts

@@ -0,0 +1,165 @@
+/**
+ * Web session model-directory and selection behavior: dynamic provider grouping,
+ * provider-local catalog failures, logged-target restoration, advisory unlisted
+ * models, and the prompt-assembly boundary for a running selection change.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import LlmService, { LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type {
+  GenerateOptions, LlmCallConfig, LlmModelInfo, LlmProviderInfo, StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`models-${String(nextRpc++)}`), payload }
+}
+
+class CatalogAdapter extends LlmAdapter {
+  constructor(
+    private readonly name: string,
+    private readonly models: readonly LlmModelInfo[] | Error,
+  ) {
+    super()
+  }
+
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: this.name }
+  }
+
+  override listModels(): Promise<readonly LlmModelInfo[]> {
+    return this.models instanceof Error
+      ? Promise.reject(this.models)
+      : Promise.resolve(this.models)
+  }
+
+  override async *stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    // Catalog tests never enter provider streaming.
+  }
+}
+
+async function harness(logged?: { provider: string; model: string }): Promise<{
+  ctx: Context
+  agent: Agent
+  sessionId: SessionId
+}> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  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(['broken'], new CatalogAdapter('Broken Provider', new Error('catalog offline')))
+  ctx.llm.registerAdapter(['empty'], new CatalogAdapter('Empty Provider', []))
+  ctx.llm.registerAdapter(['duplicate'], new CatalogAdapter('Duplicate Provider', [
+    { provider: 'duplicate', id: 'same', name: 'Same' },
+    { provider: 'duplicate', id: 'same', name: 'Same Again' },
+  ]))
+  const session = ctx.sessions.create()
+  if (logged !== undefined) {
+    session.append('request/header', { header: { config: logged }, reason: 'initial' })
+  }
+  const agent = {
+    id: session.id,
+    session,
+    status: 'running',
+    ctx,
+  } as Agent
+  ctx.agents.register(agent)
+  return { ctx, agent, sessionId: session.id }
+}
+
+function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false } }): T {
+  if (!response.result.ok) throw new Error('expected successful response')
+  return response.result.value
+}
+
+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', model: 'private-preview' })
+    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp' })
+
+    const history = expectValue(await api.sessions.history(request({ sessionId })))
+    expect(history.modelTarget).toEqual({ provider: 'deepseek', model: 'private-preview' })
+
+    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
+    expect(catalog.current).toEqual({ provider: 'deepseek', model: 'private-preview' })
+    expect(catalog.groups).toEqual([{
+      id: 'deepseek',
+      name: 'DeepSeek',
+      models: [
+        { id: 'deepseek-chat', name: 'DeepSeek Chat' },
+        { id: 'deepseek-reasoner', name: 'DeepSeek Reasoner', description: 'Reasoning model' },
+        { id: 'private-preview', name: 'private-preview', unlisted: true },
+      ],
+    }])
+    expect(catalog.failures).toEqual([
+      { id: 'broken', name: 'Broken Provider', message: 'catalog offline' },
+      {
+        id: 'duplicate',
+        name: 'Duplicate Provider',
+        message: 'adapter returned invalid or duplicate model metadata for provider "duplicate"',
+      },
+    ])
+    await ctx.fiber.dispose()
+  })
+
+  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' })
+    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
+    const signal = new AbortController().signal
+
+    expect(expectValue(await api.sessions.history(request({ sessionId }))).modelTarget)
+      .toEqual({ provider: 'deepseek', model: 'deepseek-chat' })
+    expect((await ctx.systemPrompt.assemble()).variables)
+      .toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+
+    const selected = expectValue(await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'deepseek',
+      model: 'private-preview',
+    })))
+    expect(selected.selected).toEqual({ provider: 'deepseek', model: 'private-preview' })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, seed, signal, () => Promise.resolve(seed),
+    )).resolves.toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+
+    expect((await ctx.systemPrompt.assemble()).variables)
+      .toMatchObject({ provider: 'deepseek', model: 'private-preview' })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 1, seed, signal, () => Promise.resolve(seed),
+    )).resolves.toMatchObject({ provider: 'deepseek', model: 'private-preview' })
+
+    const rejected = await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'missing',
+      model: 'model',
+    }))
+    expect(rejected.result).toEqual({
+      ok: false,
+      error: {
+        code: 'model-unavailable',
+        message: 'provider "missing" is not registered',
+        details: { provider: 'missing', model: 'model' },
+      },
+    })
+    expect(expectValue(await api.sessions.history(request({ sessionId }))).modelTarget)
+      .toEqual({ provider: 'deepseek', model: 'private-preview' })
+    await ctx.fiber.dispose()
+  })
+})