dsh-llm-providers-ui

English | 中文

Mounted owner of the LLM Providers Settings page for DeepSeek Harness.

Compatibility

Host @deepseek-ai/dsh-* packages are not version-locked: peers are * and optional. devDependencies pin the compile target (0.1.5-rc.1). Cordis stays >=4.0.2 <5.0.0.

Verified Hosts in package.json#dsh.compatibility.dshReleases are evidence, not an allowlist. Unknown newer Hosts warn once and keep the normal mount path. Only a reproduced failure is blocklisted.

Ownership

• Host owns the llm-providers settings namespace { order: string[] } (sole writer). Unloading the owner drops the namespace; reloading recreates it. Providers continue to work Host-side when the owner is absent because their llm routes are independent.
• Web (client) owns settings.section id: providers (order 12) with child settings.provider.item (keyed, root), locale settings.providers, and the nav-icon. The section and child declaration mount only while the Host-owned llm-providers scope is ready; provider plugins contribute only their keyed card via settings.provider.item.

Load order does not matter. Unloading a provider removes only its card. Unloading/reloading the owner does not corrupt provider Host services; cards reappear via the public slot lifecycle when the owner returns.

Missing owner

• Headless/Host without the owner: model routing still works.
• Web without the owner: the Providers page and its cards are omitted; provider Host routes stay live. During development, the browser console emits one owner-unavailable warning; after the owner is ready, a separate settings.section warning identifies a missing Web settings shell.

Navigation icon

The 14px globe glyph on the nav row is an isolated temporary adapter (src/client/nav-icon.ts). DSH's settings.section has no icon field, so this file patches the DOM via MutationObserver + rAF. It is idempotent and owned only here — do not duplicate it into provider plugins. When DSH exposes a public icon seam, replace this file.

Exports

• dsh-llm-providers-ui (Host): applySavedOrder, decodeProviderOrder, sortCatalogGroups, PROVIDER_ITEM_ORDER, etc. Built artifact: lib/index.js + lib/types.
• dsh-llm-providers-ui/order (pure, ESM): same order helpers, stable built utility for dsh-model-switch and provider pickers. Built artifact: lib/order.js + lib/types/order.d.ts. Provider plugins alwaysBundle this built export; do not import from src.
• dsh-llm-providers-ui/sortable (client utility, ESM): SortableList drag-reorder implementation. Built artifact: lib/sortable.js + lib/types/sortable.d.ts. Single implementation lives in src/client/SortableList.tsx and is re-exported here; provider plugins alwaysBundle the built file. Do not import from src/client/SortableList.tsx.
• dsh-llm-providers-ui/provider-ui (client utility, ESM): shared ProviderCardHeader, ProviderQuotaMeter, ProviderMark, normalizeQuotaRemaining, providerUiCss, and the header's binding to the shared usage cache, useProviderQuotaCache (with its ProviderAuthState verdict). Built artifact: lib/provider-ui.js + lib/types/provider-ui.d.ts. Single implementation lives in src/client/provider-ui.tsx and is re-exported here; provider plugins alwaysBundle the built file. Do not import from src/client/provider-ui.tsx.
• dsh-llm-providers-ui/provider-detail (client utility, ESM): the shared ProviderDetail template every provider card renders in detail mode, its providerDetailCopy locale bundle, the ProviderDetailProps/ProviderDetailModels/ProviderDetailCopy contracts, and the ProviderItemSlotContext the settings page hands to each card (mode, usage, accountState, onRefresh, copy, template). Built artifact: lib/provider-detail.js + lib/types/provider-detail.d.ts. The single implementation lives in src/client/provider-detail.tsx; provider plugins alwaysBundle the built file and render the component the page passes through the slot context. Do not import from src/client/provider-detail.tsx.
• dsh-llm-providers-ui/client (Web): owner plugin wiring and the providerDirectory Cordis service declaration. Built artifact: lib/client.js (ModuleLoader CJS) + lib/types/client; it exports only the plugin entrypoints. Do not import ./src/*.
• dsh-llm-providers-ui/model-catalog (client utility, ESM): ModelCatalogEditor, ModelPickerDialog, applyCatalogPatch, and catalog layout helpers. Built artifact: lib/model-catalog.js + lib/types/model-catalog.d.ts. Provider plugins alwaysBundle this built export; do not import from src/client.
• dsh-llm-providers-ui/usage-readers (pure, ESM): ProviderUsageReader types and vendor create*UsageReader factories for provider client bundles. Built artifact: lib/usage-readers.js + lib/types/usage-readers.d.ts. Provider plugins alwaysBundle this export. It also owns the browser last-good usage cache (readUsageCache, writeUsageCache, dropPersistedUsageKeys, peekCachedUsage, rememberCachedUsage, rememberHeadlineQuota, headerQuotaFromCache, clearProviderUsageCache): readable storage is authoritative (including empty after invalidation) with memory only as an unavailable-storage fallback; stale status persists honestly; collapsed-header headlines never replace a full multi-window summary and record no fetch time; invalidation flows through ctx.providerDirectory.invalidateUsage(key).

The package exposes only the built lib/ entrypoints listed above; consumers should import those package exports rather than source paths.

Installation

This package is a bundle and must be listed in the profile. Until DSH mounts transitive bundles, install it alongside every provider card:

dsh plugin --profile web add --force \
  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.8.tgz

No strict load order with providers is required. See cordis.patch.yml.

Consumer contract

Provider plugins register their card under settings.provider.item with their settingsNs key and register { key, role, header, usage } on ctx.providerDirectory inside an effect. The returned disposer owns the registration. Usage-enabled providers import their reader factory from dsh-llm-providers-ui/usage-readers. Unregistered cards keep the LLM badge and do not receive a Provider Usage tile. The sidebar usage stage sizes to its rendered tiles (natural grid height up to the three-row cap, then scrolls), so hiding providers shrinks the panel instead of leaving blank rows. Quota and unavailable-status headlines stay on one line with ellipsis, keeping tiles equal-height and three rows fully visible at narrow sidebar widths. Migrated cards render the shared header from dsh-llm-providers-ui/provider-ui (ProviderCardHeader with role, caller status, and headline quota; title/mark/summary/open/unsaved keep the legacy codex layout), mark their root li[data-provider-card][data-provider-role], their header button data-provider-card-header, and their body data-provider-body, include one <style>{providerUiCss}</style>, and declare header: 'shared' so the shell drops its fallback badge. Cards start their existing cached quota read when account readiness is known, independent of expansion; opening an already-loaded card does not refetch. Missing quota renders no meter, never a zero bar; normalizeQuotaRemaining keeps precision and reports NaN/Infinity/out-of-range as unavailable. The settings fallback preserves ancestor overflow clipping and the native settings title. Mobile layouts keep ownership of offscreen panels and dialog header spacing.

Provider plugins import directory and slot types from dsh-llm-providers-ui/client with import type {} and must not duplicate the module augmentations locally. After sign-out or account switch, providers call ctx.providerDirectory.invalidateUsage(key) so the sidebar drops the cached quota and refetches; a Settings card reports the same event through useProviderQuotaCache's signedOut verdict, which purges the stored entry. Transient read errors still show the last good windows as stale in the sidebar, while a card keeps its truthful unavailable dash. dsh-model-switch reuses sortCatalogGroups via the built dsh-llm-providers-ui/order export.

Until this package is published to npm, lab checkouts may use link:../dsh-llm-providers-ui in dev, but workspace package.json must not commit link: specs.

Release installation (Latest)

Shared LLM Providers settings page, navigation, card order, and picker sort owner. The published pack contains built Host/Client files only; it has no sibling-repository source, workstation path, link:, or workspace: dependency. Pack-check fixtures and compile-target devDependencies are 0.1.5-rc.1.

Latest installation (asset name matches the current latest tarball):

dsh plugin --profile web add --force \
  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.8.tgz

Fixed-version installation (v0.2.8):

dsh plugin --profile web add --force \
  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.8/dsh-llm-providers-ui-0.2.8.tgz

Update, uninstall, and verify:

# Update to Latest
dsh plugin --profile web add --force \
  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.8.tgz
# Verify the loaded version
dsh plugin --profile web list
dsh plugin --profile web doctor
# Uninstall only this plugin
dsh plugin --profile web remove dsh-llm-providers-ui

Configuration: use the plugin section in Settings for Web UI plugins, or the profile dsh.profile.bundles entry for Host-only plugins. Start with this README's minimal YAML/JSON example and provide credentials/backend addresses explicitly.

Rollback: reinstall the previously recorded immutable tarball, verify the profile list, then restart the Web service once. Inspect journalctl --user -u dsh-web.service; never put a source checkout in the production profile.

Verify release assets against the SHA-256 manifest attached to the selected release.

Codex quota reads explicitly refresh the backend; the UI store controls caching for both manual refresh and expired-cache polling.

Live lab UI check

With an isolated Chrome exposing CDP on port 9229 and authenticated to the existing 3082 lab, run node scripts/check-lab-settings.mjs. The check covers seven real Provider cards and their brand/role icons at 1280, 390 and 320 pixels in light/dark themes, including expanded Antigravity. It restores the prior theme, does not edit Provider credentials or configuration, and writes screenshots to /tmp/lab-*.png. The script does not start a replacement application server.