English | 中文
dsh-catalog-refresh
Rebuild the model catalogues DSH serves at runtime, so OpenRouter, OpenCode,
Fireworks, and friends show the live model lists instead of the stale
snapshot baked into the @earendil-works/pi-ai version DSH pins.
Why this exists
DSH gets every LLM provider model list from the @earendil-works/pi-ai
package it bundles: dsh-llm-pi-ai reads pi-ai's static MODELS registry
(dist/providers/data/*.json, generated when pi-ai publishes). The model
picker, the Models page discovery probe, and request routing all serve that
baked-in list — so when OpenRouter adds a model after a pi-ai release, DSH
users must hand-add custom models until DSH bumps pi-ai.
This plugin fetches the providers' own live model endpoints at boot (and
then on a cadence), converts them into pi-ai Model entries, and patches
the harness's pi-ai MODELS registry in place — the same module instance
dsh-llm-pi-ai reads. Patching MODELS alone is not enough for the model
picker: dsh-llm-pi-ai materializes each route's model list when its
settings section changes, so the plugin also writes a per-refresh stamp
into the declared providers' headers in the llm-pi-ai settings section
(a deep merge; nothing configured is touched). That makes dsh-llm-pi-ai
re-resolve its routes against the patched registry, so the picker updates
live — no restart required.
Sources
| provider | endpoint | auth | detail |
|---|
| openrouter | https://openrouter.ai/api/v1/models | public | full (pricing, context, max tokens, reasoning, modalities) |
| opencode | https://opencode.ai/zen/v1/models | public | id list; installed metadata kept, new ids routed by prefix |
| fireworks | https://api.fireworks.ai/inference/v1/models | API key | id + context, vision, chat flags |
| groq | https://api.groq.com/openai/v1/models | API key | id + context, max tokens, modalities |
| together | https://api.together.ai/v1/models | API key | id list; installed metadata kept |
| deepseek | https://api.deepseek.com/models | API key | id list; installed metadata kept |
Key-gated sources use the conventional environment variable
(FIREWORKS_API_KEY, GROQ_API_KEY, TOGETHER_API_KEY, DEEPSEEK_API_KEY)
or the credential record DSH's Models page stores (llm-pi-ai/<provider>).
Without a key the source is skipped and the installed catalogue stays in
place.
How it patches
- Locates the pi-ai package the running harness imports, anchored on the
dsh CLI entry that started the process (process.argv[1] →
@deepseek-ai/dsh-llm-pi-ai → @earendil-works/pi-ai).
- Imports that package's
dist/models.generated.js by file URL — Node's
module cache keyed by URL makes it the same instance dsh-llm-pi-ai
reads via @earendil-works/pi-ai/providers/all.
- Replaces
MODELS[provider] with the rebuilt map. Discovery calls read
the registry live, so the Models-page probe is immediately fresh.
- Nudges the picker.
dsh-llm-pi-ai only re-materializes a route's
model list when its settings section changes, and the picker
(llm.models / session.models) serves those materialized lists. So
after every patch the plugin writes a fresh stamp into each declared
provider's headers in the llm-pi-ai settings section (settings.yaml
gains an x-catalog-refresh: <timestamp> entry — inert, and the deep
merge leaves every other field intact). The section change makes
dsh-llm-pi-ai re-resolve its routes against the patched registry, so
the picker shows the rebuilt catalogue immediately.
Boot runs the cache round first (no network, so the picker resolves fresh
data as early as possible), then the live round; both nudge. The stamp is
fingerprint-gated: a provider is only nudged when its model set actually
changed (or once per boot), so settings.yaml is not rewritten on every
restart.
Merging rules: for OpenRouter the live entry wins (pricing, context, max
tokens, reasoning, modalities) while curated fields (compat,
thinkingLevelMap) carry over from the installed entry when present. For
id-list sources, installed entries stay authoritative for curated fields
(compat, thinkingLevelMap, reasoning, cost, wire protocol) while the
live listing refreshes the structural facts the endpoint reports
(context window, max tokens, input modalities, name) — Fireworks and Groq
both publish these — and unknown ids are added with structural defaults.
Entries the endpoint reports as non-chat (speech/audio output such as Groq's
whisper/orpheus) are dropped: they cannot serve chat traffic.
Fetched lists are cached under $DSH_HOME/catalog-refresh/; a restart
without network still applies the last good refresh.
Reasoning-effort support
dsh-llm-pi-ai only shows the composer's reasoning-effort selector for
models that declare effort metadata. The pi-ai catalogue ships none, and the
dsh-thinking-effort plugin only covers hand-declared settings models — so
catalogue-served models lost the selector after the rebuild. This plugin
bakes a default thinkingLevelMap into every rebuilt reasoning model,
mirroring dsh-thinking-effort's official preset:
- Off / High / Max for reasoning models (OpenRouter's
openai-completions wire receives reasoning: { effort: "high" | "max" }),
- no effort control for non-reasoning models (same as before).
The offered levels come from CATALOG_REFRESH_EFFORTS (comma-separated level
ids; off is always supported). For example
CATALOG_REFRESH_EFFORTS=off,low,medium,high offers Off/Low/Medium/High
instead. Custom gateway spellings (e.g. sending ultra for High) still need
per-model reasoningEfforts in the llm-pi-ai settings document — this
plugin only provides the catalogue default.
Id-list sources (opencode, fireworks, groq, together, deepseek) return model
ids only — no capability metadata. Known ids keep the installed catalogue's
flags; unknown ids assume reasoning-capable (the overwhelming case for
chat models), so new models like Fireworks glm-5p3 get the effort selector
immediately. Definitively non-reasoning families (Fireworks
*-embedding-* / *-reranker-*) are excluded and never advertise effort.
Fireworks wire note. Fireworks validates Anthropic-style
thinking.budget_tokens strictly and rejects requests where
max_tokens is not strictly greater than the budget (a 400 this plugin's
effort support surfaced). The plugin therefore routes all Fireworks
models through Fireworks' native OpenAI-compatible endpoint with
reasoning_effort (low/medium/high/max all accepted), which avoids
budget validation entirely. Off on a Fireworks reasoning model maps to the
provider default — Fireworks rejects disabling thinking on thinking models,
so that is the closest equivalent.
Configuration (environment)
| variable | meaning | default |
|---|
CATALOG_REFRESH_DISABLE | 1 disables the plugin entirely | off |
CATALOG_REFRESH_INTERVAL_HOURS | re-fetch cadence | 12 |
CATALOG_REFRESH_HOME | cache directory override | $DSH_HOME or ~/.dsh |
CATALOG_REFRESH_EFFORTS | offered reasoning levels for rebuilt models | off,high,max |
Install
dsh plugin --profile <profile> add dsh-catalog-refresh
Boot output shows one line per source:
[dsh-catalog-refresh] openrouter: patched 396 models (live)
[dsh-catalog-refresh] opencode: patched 67 models (live)
[dsh-catalog-refresh] fireworks: skipped (… answered 401)
Operational notes
- pnpm copies the package into the profile at install time. After editing
the plugin source, run
pnpm install again in the profile (the profile's
node_modules/dsh-catalog-refresh is a snapshot, not a symlink),
then restart dsh web.
- Key-gated sources (fireworks, groq, together, deepseek, …) use the
conventional environment variable or the credential record DSH's Models page
stores (
llm-pi-ai/<provider>).
- The patch is live only in the running process; restarting the app re-runs
the refresh (cached lists apply first if the network is unavailable).
settings.yaml gains an x-catalog-refresh header per declared
provider — this is the re-resolution nudge, not a configuration change.
It is safe to delete; the next refresh rewrites it.
Development
npm run check # syntax-check the modules
npm test # unit tests (conversion, merge, cache-first patch, nudge) — no network, no machine-specific paths
