dsh-code 0.9.1 → 1.0.0

package/src/keyboard.ts

@@ -0,0 +1,125 @@
+/**
+ * Keyboard enhancement protocol (Codex `keyboard_modes` parity) and the
+ * kitty CSI-u normalization layer.
+ *
+ * The TUI pushes the kitty keyboard protocol with DISAMBIGUATE_ESCAPE_CODES
+ * and REPORT_ALTERNATE_KEYS (flags 1|4 = `\x1b[>5u`), which makes terminals
+ * report Shift+Enter as `CSI 13;2u` instead of a bare CR. Event types are
+ * deliberately NOT requested: Ink 5's parser cannot decode the
+ * `:event-type` suffix, and repeat/release reporting buys this surface
+ * nothing.
+ *
+ * Ink 5 also cannot parse most CSI-u forms at all — they fall through its
+ * regex as unnamed sequences and get INSERTED AS DRAFT TEXT. The composer's
+ * stdin read patch therefore rewrites every CSI-u form it can decode back
+ * to the legacy byte or canonical sequence the existing key handling
+ * already understands, before Ink ever parses the chunk.
+ *
+ * @module @deepseek-ai/dsh-code/keyboard
+ */
+
+/** Push keyboard enhancement (modifyOtherKeys off, kitty flags 1|4). */
+export const KEYBOARD_ENHANCE_ENABLE = '\x1b[>4;0m\x1b[>5u'
+
+/** Pop the enhancement stack and reset modifyOtherKeys (exit path). */
+export const KEYBOARD_ENHANCE_DISABLE = '\x1b[<u\x1b[>4;0m'
+
+/** Enable bracketed paste reporting. */
+export const BRACKETED_PASTE_ENABLE = '\x1b[?2004h'
+
+/** Disable bracketed paste reporting. */
+export const BRACKETED_PASTE_DISABLE = '\x1b[?2004l'
+
+/** Bracketed paste markers as Ink delivers them (it strips the leading ESC). */
+export const PASTE_START_MARKER = '[200~'
+export const PASTE_END_MARKER = '[201~'
+
+/**
+ * Remove bracketed paste markers from one input chunk. Panel drafts accept raw
+ * `input` text, where an unhandled paste would otherwise persist the literal
+ * "[200~"/"[201~" markers Ink leaves after stripping the ESC byte.
+ */
+export function stripPasteMarkers(text: string): string {
+  return text.replaceAll(PASTE_START_MARKER, '').replaceAll(PASTE_END_MARKER, '')
+}
+
+/** One decoded CSI-u keypress: key code, 1-based modifier param, alternate code. */
+interface CsiUKey {
+  code: number
+  modifiers: number
+  alternate?: number
+}
+
+/** Match one CSI-u sequence (code, optional ;modifiers, then :event or ;alternate). */
+const CSI_U_SOURCE = '\x1b\\[(\\d+)(?:;(\\d+))?(?:[:;](\\d+))?u'
+
+/** Legacy equivalent for one decoded CSI-u key, or undefined to pass through. */
+function legacyForKey(key: CsiUKey): string | undefined {
+  const bits = Math.max(0, key.modifiers - 1)
+  const shift = (bits & 1) !== 0
+  const alt = (bits & 2) !== 0
+  const ctrl = (bits & 4) !== 0
+  if (key.code === 13) {
+    // Enter: shift keeps the canonical enhanced form the composer detects;
+    // ctrl maps to LF (the Ctrl+J newline binding), alt to ESC+CR.
+    if (shift) return '\x1b[13;2u'
+    if (ctrl) return '\n'
+    if (alt) return '\x1b\r'
+    return '\r'
+  }
+  if (key.code === 27) return '\x1b'
+  if (key.code === 9) return shift ? '\x1b[Z' : '\t'
+  if (key.code === 127) return alt || ctrl ? '\x1b\x7f' : '\x7f'
+  // Kitty disambiguate mode reports the six legacy functional keys as CSI u
+  // codes 1-6 (Home, Insert, Delete, End, PageUp, PageDown). Ink 5 cannot
+  // parse these forms and would insert literal "[3u" text into the draft, so
+  // rewrite them to the legacy sequences the input layer already annotates.
+  // The modifier parameter passes through: kitty and xterm share the same
+  // 1+bit-field encoding (shift 2, alt 3, ctrl 5, ...). Lock-key bits are
+  // dropped because the legacy sequences cannot express them.
+  if (key.code >= 1 && key.code <= 6) {
+    const mask = (shift ? 1 : 0) + (alt ? 2 : 0) + (ctrl ? 4 : 0)
+    const mods = mask === 0 ? '' : `;${mask + 1}`
+    if (key.code === 1) return mods === '' ? '\x1b[H' : `\x1b[1${mods}H`
+    if (key.code === 4) return mods === '' ? '\x1b[F' : `\x1b[1${mods}F`
+    return `\x1b[${key.code}${mods}~`
+  }
+  if (key.code >= 97 && key.code <= 122) {
+    const letter = String.fromCodePoint(key.code)
+    if (ctrl) return String.fromCodePoint(key.code - 96)
+    if (alt) return '\x1b' + letter
+    if (shift) return String.fromCodePoint(key.alternate ?? key.code - 32)
+    return letter
+  }
+  if (key.code >= 65 && key.code <= 90) {
+    if (ctrl) return String.fromCodePoint(key.code + 32 - 96)
+    if (alt) return '\x1b' + String.fromCodePoint(key.code + 32)
+    return String.fromCodePoint(key.code)
+  }
+  if (key.code >= 32 && key.code <= 126 && key.alternate !== undefined) {
+    const base = key.alternate >= 97 && key.alternate <= 122 ? key.alternate : key.code
+    if (ctrl && base - 96 >= 1 && base - 96 <= 26) return String.fromCodePoint(base - 96)
+    if (alt) return '\x1b' + String.fromCodePoint(key.alternate)
+    return String.fromCodePoint(key.alternate)
+  }
+  return undefined
+}
+
+/**
+ * Rewrite every decodable kitty CSI-u sequence in one stdin chunk to the
+ * legacy form the input layer already handles. Undecodable or non-key
+ * sequences pass through untouched, so terminals without the protocol are
+ * unaffected.
+ */
+export function normalizeKeyboardChunk(chunk: string): string {
+  if (!chunk.includes('\x1b[') || !chunk.includes('u')) return chunk
+  const pattern = new RegExp(CSI_U_SOURCE, 'g')
+  return chunk.replace(pattern, (whole, code: string, mods?: string, third?: string) => {
+    const legacy = legacyForKey({
+      code: Number.parseInt(code, 10),
+      modifiers: mods === undefined || mods === '' ? 1 : Math.max(1, Number.parseInt(mods, 10)),
+      alternate: third !== undefined && third !== '' ? Number.parseInt(third, 10) : undefined,
+    })
+    return legacy ?? whole
+  })
+}

package/src/mentions.ts

@@ -1,25 +1,33 @@
 /**
- * Workspace @mention support: file and directory candidates from a bounded
- * async scan of the session cwd, session candidates from the opt-in
- * `sessionReferenceResolver` service, and submission preparation through its
- * `prepare()` API. Picked session mentions land as canonical
- * `@[label](dsh-session:…)` tokens; on submit the text is parsed back into
- * readable `@label` text plus structured references, snapshots are injected
- * via `agent.inject()` before the readable message wakes the driver
+ * Workspace @mention support: file and directory candidates from the
+ * `fileReferences` service (dsh-file-reference-local), session candidates
+ * from the opt-in `sessionReferenceResolver` service, and submission
+ * preparation through its `prepare()` API. Picked session mentions land as
+ * canonical `@[label](dsh-session:…)` tokens; on submit the text is parsed
+ * back into readable `@label` text plus structured references, snapshots are
+ * injected via `agent.inject()` before the readable message wakes the driver
  * (`followup` idle, `steer` running) — exactly the upstream README's wiring.
  *
- * Harness exposes no workspace-file mention service (only session references
- * plus a post-hoc produced-file linker), so the file index is the lightweight
- * bounded scan below, kept deliberately smaller than Codex's streaming
- * gitignore-aware walker.
+ * File discovery lives entirely in the Harness service (per-agent bounded
+ * index, `@dir/` listing, symlink guards, tool/result invalidation); this
+ * module only maps candidates to menu rows and never re-implements scanning.
+ * The service is agent-scoped (the agent supplies the session cwd and the
+ * cache key), so before the first session creates an agent the SAME official
+ * search class runs against the launch cwd — @ file completion works on a
+ * bare launch, model- and session-independent, and the agent-scoped service
+ * takes over once a session exists.
  *
  * @module @deepseek-ai/dsh-code/mentions
  */
 
-import { readdir } from 'node:fs/promises'
-import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import {
+  DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES,
+  DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+  DEFAULT_FILE_SEARCH_MAX_RESULTS,
+  WorkspaceFileSearch,
+} from '@deepseek-ai/dsh-file-reference-local'
 import {
   formatSessionReferenceMention,
   parseSessionReferenceText,
@@ -30,14 +38,6 @@ import {
 /** Parsed submission text: readable text plus structured references. */
 type ParsedSessionReferenceText = ReturnType<typeof parseSessionReferenceText>
 
-/** One filesystem entry the @ menu can complete. */
-export interface FileCandidate {
-  /** Workspace-relative path with forward slashes. */
-  path: string
-  /** Entry kind; directories insert with a trailing slash. */
-  kind: 'file' | 'directory'
-}
-
 /** One merged menu candidate (files and sessions, already ranked). */
 export interface MentionCandidate {
   /** Text inserted after the `@` (directories carry a trailing slash). */
@@ -58,76 +58,22 @@ export interface PreparedMention {
   additionalContext?: import('@deepseek-ai/dsh-session').UserMessage
 }
 
-/** Directories never entered and files never listed during the scan. */
-const SKIP_DIRS = new Set(['.git', 'node_modules', 'lib', 'dist', 'out', '.omc', 'coverage'])
-const MAX_FILES = 4000
-const MAX_DEPTH = 12
-/** Empty-query default rows: proves the index exists without typing (Codex's
- * popups show something on a bare sigil too). */
-const EMPTY_QUERY_ROWS = 20
-
-/**
- * Bounded async BFS scan of a workspace; unreadable entries are skipped.
- * Both files and directories are indexed (directories insert with a trailing
- * slash), mirroring Codex's `MatchType::{File,Directory}` index. Dotfiles and
- * the {@link SKIP_DIRS} list are excluded, which is a coarser filter than
- * Codex's gitignore-aware walker but stays dependency-free and bounded.
- */
-export async function scanWorkspaceFiles(root: string, signal?: AbortSignal): Promise<readonly FileCandidate[]> {
-  const found: FileCandidate[] = []
-  const pending: Array<{ absolute: string; relative: string; depth: number }> = [{ absolute: root, relative: '', depth: 0 }]
-  const aborted = (): boolean => signal?.aborted === true
-  while (pending.length > 0 && found.length < MAX_FILES && !aborted()) {
-    const current = pending.shift()
-    if (current === undefined) break
-    let entries
-    try {
-      entries = await readdir(current.absolute, { withFileTypes: true })
-    } catch {
-      continue
-    }
-    for (const entry of entries) {
-      if (found.length >= MAX_FILES || aborted()) return found
-      if (entry.name.startsWith('.')) continue
-      const relative = current.relative === '' ? entry.name : `${current.relative}/${entry.name}`
-      if (entry.isDirectory()) {
-        if (SKIP_DIRS.has(entry.name) || current.depth + 1 > MAX_DEPTH) continue
-        found.push({ path: relative, kind: 'directory' })
-        pending.push({ absolute: join(current.absolute, entry.name), relative, depth: current.depth + 1 })
-      } else if (entry.isFile()) {
-        found.push({ path: relative, kind: 'file' })
-      }
-    }
-  }
-  return found.sort((left, right) => left.path < right.path ? -1 : 1)
+/** One path candidate the `ctx.fileReferences` service returns. */
+interface ServiceFileCandidate {
+  readonly path: string
+  readonly kind: 'file' | 'directory'
 }
 
-/** True when every query character appears in order in the haystack. */
-function isSubsequence(query: string, haystack: string): boolean {
-  let at = 0
-  for (const char of haystack) {
-    if (char === query[at]) at += 1
-    if (at >= query.length) return true
-  }
-  return at >= query.length
+/** The `ctx.fileReferences` service face (dsh-file-reference-local). */
+interface FileReferenceServiceLike {
+  list(agent: Agent, query: string, signal: AbortSignal): Promise<readonly ServiceFileCandidate[]>
 }
 
-/** Rank one file path against the typed query (community-TUI scoring shape). */
-function scoreFile(path: string, query: string): number {
-  const name = path.slice(path.lastIndexOf('/') + 1)
-  if (query === '') return 0
-  if (name === query) return 1000
-  if (name.startsWith(query)) return 900
-  if (name.includes(query)) return 700
-  if (path.includes(query)) return 500
-  if (isSubsequence(query, name)) return 300
-  return 0
-}
+/** Menu cap on file rows; the service owns ranking and default rows. */
+const MAX_FILE_ROWS = 20
 
 /** The mention API the input editor and the runner share. */
 export interface MentionsApi {
-  /** Scanned workspace files and directories, cached across one session. */
-  files(): Promise<readonly FileCandidate[]>
   /** Ranked menu candidates for the typed `@` query. */
   candidates(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]>
   /** Parse submission text into readable text plus structured references. */
@@ -143,53 +89,62 @@ export interface MentionsApi {
 
 /**
  * Create the mention API for one agent's workspace. A missing
- * session-reference service degrades to file mentions only (the scan still
- * works); `prepare` then passes text through untouched. An undefined agent
- * (a bare launch before any session exists) also degrades to file-only
- * mentions, so `@` file completion works before the first message.
+ * `fileReferences` service (with an agent present) or `sessionReferenceResolver`
+ * degrades that half to empty rows; `prepare` passes text through untouched
+ * without references. An undefined agent (a bare launch before any session
+ * exists) runs the official WorkspaceFileSearch over the launch cwd — the
+ * same class the mounted service uses per agent — so `@` file completion
+ * works from the first keystroke; session references wait for the session.
  *
- * `files` is hoisted into the closure so `candidates` never reaches for
- * `this` — the runner hands `mentions.candidates` to the input editor as a
- * detached callback, and a `this`-bound method would throw on every `@` key.
- * @param ctx - context carrying the optional `sessionReferenceResolver`.
- * @param agent - the session owner; excluded from its own candidates.
- * @param cwd - workspace root to scan.
+ * `candidates` never reaches for `this` — the runner hands it to the input
+ * editor as a detached callback, and a `this`-bound method would throw on
+ * every `@` key.
+ * @param ctx - context carrying the optional `fileReferences` and
+ * `sessionReferenceResolver` services.
+ * @param agent - the session owner; excluded from its own session candidates.
+ * @param cwd - launch working directory; bounds the pre-session search.
  */
 export function createMentions(ctx: Context, agent: Agent | undefined, cwd: string): MentionsApi {
   const resolver = ctx.get('sessionReferenceResolver')
+  const fileReferences = (ctx as unknown as { get(name: string): unknown }).get('fileReferences') as
+    | FileReferenceServiceLike
+    | undefined
   const sessionCapable = agent !== undefined && resolver !== undefined
-  let filesPromise: Promise<readonly FileCandidate[]> | undefined
-  const files = (): Promise<readonly FileCandidate[]> => {
-    filesPromise ??= scanWorkspaceFiles(cwd)
-    return filesPromise
+  // Pre-session fallback: one lazily built search over the launch cwd with
+  // the official defaults — pure in-memory index, no handles to release.
+  let preSessionSearch: WorkspaceFileSearch | undefined
+  const preSessionFiles = (query: string, signal?: AbortSignal): Promise<readonly ServiceFileCandidate[]> => {
+    preSessionSearch ??= new WorkspaceFileSearch(cwd, {
+      maxResults: DEFAULT_FILE_SEARCH_MAX_RESULTS,
+      maxEntries: DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+      excludedDirectories: [...DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES],
+    })
+    return preSessionSearch.list(query, signal ?? new AbortController().signal)
   }
 
   return {
-    files,
     async candidates(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]> {
       const needle = query.trim()
-      const [scanned, sessions] = await Promise.all([
-        files(),
+      const [files, sessions] = await Promise.all([
+        agent !== undefined && fileReferences !== undefined
+          ? fileReferences
+            .list(agent, needle, signal ?? new AbortController().signal)
+            .catch(() => [] as readonly ServiceFileCandidate[])
+          : agent === undefined
+            ? preSessionFiles(needle, signal).catch(() => [] as readonly ServiceFileCandidate[])
+            : Promise.resolve([] as readonly ServiceFileCandidate[]),
         sessionCapable && needle !== '' && agent !== undefined
           ? resolver!.listCandidates(agent, needle, 10, signal).catch(() => [] as readonly SessionReferenceCandidate[])
           : Promise.resolve([] as readonly SessionReferenceCandidate[]),
       ])
-      // A bare `@` lists the first path-sorted entries so the menu is live
-      // before any typing; a non-empty needle ranks by the Codex-shaped score.
-      const fileRows: MentionCandidate[] = (needle === ''
-        ? scanned.slice(0, EMPTY_QUERY_ROWS)
-        : scanned
-          .filter(candidate => scoreFile(candidate.path, needle) > 0)
-          .sort((left, right) => scoreFile(right.path, needle) - scoreFile(left.path, needle))
-          .slice(0, 20))
-        .map(candidate => ({
-          label: candidate.path,
-          description: candidate.kind === 'directory' ? 'Folder' : 'File',
-          kind: candidate.kind,
-        }))
-      // Sessions join only with a typed needle and always AFTER the file
-      // rows: `@` is a file mention first (Codex's semantics), and session
-      // references are the secondary vocabulary.
+      // The service owns ranking (and the bare-@ default rows); the menu caps
+      // file rows and always places sessions after files — `@` is a file
+      // mention first (Codex's semantics), session references second.
+      const fileRows: MentionCandidate[] = files.slice(0, MAX_FILE_ROWS).map(candidate => ({
+        label: candidate.path,
+        description: candidate.kind === 'directory' ? 'Folder' : 'File',
+        kind: candidate.kind,
+      }))
       const sessionRows: MentionCandidate[] = sessions.map(candidate => ({
         label: formatSessionReferenceMention(candidate),
         description: `Session · ${candidate.cwd ?? '(no cwd)'}`,

package/src/presets.ts

@@ -1,7 +1,7 @@
 /** Agent-preset policy kept independent from the Ink surface. */
 
 import type { Context } from '@deepseek-ai/cordis'
-import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 
 /** One discoverable agent composition. */
@@ -71,6 +71,3 @@ export async function switchPreset(
   writable.append('agent-preset/selected', { agentPreset: preset.id })
   return preset
 }
-
-/** Minimal handle shape used by lifecycle tests without exposing Agent internals. */
-export type OwnedAgent = Pick<AgentHandle, 'agent' | 'dispose'>

package/src/provider-settings.ts

@@ -129,6 +129,28 @@ function profileRefOf(profile: unknown): string | undefined {
   return typeof ref === 'string' && ref.length > 0 ? ref : undefined
 }
 
+/** Extract only fields the terminal can round-trip without touching provider-specific extras. */
+function configurationOf(profile: unknown): ProviderConfiguration {
+  if (typeof profile !== 'object' || profile === null) return { models: [] }
+  const record = profile as Record<string, unknown>
+  const source = Array.isArray(record.models) ? record.models : []
+  const models = source.flatMap((value): ProviderModelSettings[] => {
+    if (typeof value !== 'object' || value === null) return []
+    const entry = value as Record<string, unknown>
+    if (typeof entry.id !== 'string' || entry.id.trim() === '') return []
+    return [{
+      id: entry.id,
+      ...(typeof entry.name === 'string' && entry.name.trim() !== '' ? { name: entry.name } : {}),
+      ...(typeof entry.contextWindow === 'number' && Number.isFinite(entry.contextWindow) ? { contextWindow: entry.contextWindow } : {}),
+      ...(typeof entry.maxTokens === 'number' && Number.isFinite(entry.maxTokens) ? { maxTokens: entry.maxTokens } : {}),
+    }]
+  })
+  return {
+    ...(typeof record.baseURL === 'string' && record.baseURL.trim() !== '' ? { baseURL: record.baseURL } : {}),
+    models,
+  }
+}
+
 /* ------------------------------------------------------------------ *
  * Exported contracts.
  * ------------------------------------------------------------------ */
@@ -166,6 +188,20 @@ export type ProviderCredentialView =
   | ({ readonly kind: 'facts' } & ProviderCredentialFacts)
   | { readonly kind: 'error'; readonly message: string }
 
+/** One explicit model enabled for a provider profile. */
+export interface ProviderModelSettings {
+  readonly id: string
+  readonly name?: string
+  readonly contextWindow?: number
+  readonly maxTokens?: number
+}
+
+/** The small, portable subset of a provider profile the terminal edits. */
+export interface ProviderConfiguration {
+  readonly baseURL?: string
+  readonly models: readonly ProviderModelSettings[]
+}
+
 /**
  * One provider row in the TUI provider-management panel: the configurable
  * directory entry joined with its settings profile and credential facts.
@@ -195,6 +231,8 @@ export interface ProviderTargetView {
   readonly suggestedRef: string
   /** Credential facts, a bounded describe error, or undefined when there is no ref to describe. */
   readonly credential: ProviderCredentialView | undefined
+  /** Endpoint and explicit model overrides visible to the provider editor. */
+  readonly configuration: ProviderConfiguration
   /** The owning adapter reports this route as hand-declared (absent when it draws no distinction). */
   readonly declared?: boolean
 }
@@ -339,6 +377,7 @@ export async function loadProviderSettings(ctx: Context): Promise<ProviderSettin
       settingsRevision: namespace?.revision ?? 0,
       configured,
       removable,
+      configuration: configurationOf(profile),
       ...credentialRef === undefined ? {} : { credentialRef },
       suggestedRef: deriveCredentialRef(base.provider),
       ...base.declared === undefined ? {} : { declared: base.declared },
@@ -441,6 +480,61 @@ export async function saveProviderCredential(ctx: Context, target: ProviderTarge
   }
 }
 
+/** Save the endpoint and an explicit model allow-list without rebuilding the profile. */
+export async function saveProviderConfiguration(
+  ctx: Context,
+  target: ProviderTargetView,
+  configuration: ProviderConfiguration,
+): Promise<void> {
+  if (target.settingsNs.length === 0) {
+    throw new ProviderSettingsError(`provider "${target.provider}" has no managed settings namespace; configure it in settings.yaml`)
+  }
+  const settings = ctx.get('settings') as SettingsFace | undefined
+  if (settings === undefined || settings.writable !== true) {
+    throw new ProviderSettingsError('settings are read-only; provider configuration cannot be changed here')
+  }
+  const baseURL = configuration.baseURL?.trim()
+  if (baseURL !== undefined && baseURL !== '') {
+    try {
+      const parsed = new URL(baseURL)
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') throw new Error('unsupported protocol')
+    } catch {
+      throw new ProviderSettingsError('base URL must be an absolute http or https URL')
+    }
+  }
+  const seen = new Set<string>()
+  const models = configuration.models.map((model) => {
+    const id = model.id.trim()
+    if (id === '' || seen.has(id)) throw new ProviderSettingsError('each selected model must have a unique non-empty id')
+    seen.add(id)
+    for (const [label, value] of [['context window', model.contextWindow], ['output window', model.maxTokens]] as const) {
+      if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+        throw new ProviderSettingsError(`${label} must be a positive integer`)
+      }
+    }
+    return {
+      id,
+      ...(model.name === undefined || model.name.trim() === '' ? {} : { name: model.name.trim() }),
+      ...(model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow }),
+      ...(model.maxTokens === undefined ? {} : { maxTokens: model.maxTokens }),
+    }
+  })
+  const root = target.settingsPath
+  const ops: SettingsPathOpFace[] = [
+    baseURL === undefined || baseURL === ''
+      ? { op: 'unset', path: [...root, 'baseURL'] }
+      : { op: 'set', path: [...root, 'baseURL'], value: baseURL },
+    // An explicit empty list is deliberate: it prevents a provider's shipped
+    // catalog from silently becoming the active selection.
+    { op: 'set', path: [...root, 'models'], value: models },
+  ]
+  try {
+    await settings.mutate(target.settingsNs, ops, target.settingsRevision)
+  } catch (error) {
+    throw new ProviderSettingsError(singleLine(messageOf(error)))
+  }
+}
+
 /**
  * Remove the currently named credential without touching the provider
  * profile. Only the resolved profile's own reference is unset; a dormant or