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

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

1. 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).
2. 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.
3. Replaces MODELS[provider] with the rebuilt map. Discovery calls read
   the registry live, so the Models-page probe is immediately fresh.
4. 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)

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