DSH uses a static model list from the @earendil-works/pi-ai package by default. When providers such as OpenRouter and Fireworks release new models, those models do not immediately appear in DSH’s model selector or discovery probes; you must wait for a version update of the pi-ai package.

The dsh-catalog-refresh plugin fetches real-time model lists from provider APIs when DSH starts (and on a scheduled interval), converts them into pi-ai Model entries, and directly patches the harness MODELS registry. It also writes a header to trigger dsh-llm-pi-ai to re-resolve routing, updating the model selector in real time without a restart.

Features

  • Automatically rebuilds DSH’s runtime model catalog.
  • Fetches real-time model lists from OpenRouter, OpenCode Zen, Fireworks, Groq, Together, and DeepSeek.
  • Patches DSH’s pi-ai MODELS registry.
  • Updates the model selector in real time by writing a header.
  • Supports reasoning effort levels (CATALOG_REFRESH_EFFORTS).
  • Handles Fireworks reasoning budget validation.

Installation and Enablement

Install the plugin using the official command:

dsh plugin --profile <profile> add dsh-catalog-refresh

Configuration and Environment Variables

After installation, the plugin behavior can be controlled through environment variables:

  • Refresh interval
    Sets the interval for re-fetching the model list.
  CATALOG_REFRESH_INTERVAL_HOURS=24

The default is 12 hours.

  • Reasoning effort levels
    Specifies the reasoning levels provided when rebuilding models, comma-separated. For example, provide off,low,medium,high.
  CATALOG_REFRESH_EFFORTS=off,low,medium,high

The default is off,high,max.

  • Cache directory
    Specifies where the fetched model lists are cached.
  CATALOG_REFRESH_HOME=/path/to/cache

Defaults to $DSH_HOME or ~/.dsh.

  • Disable plugin
    Set to 1 to fully disable the plugin.
  CATALOG_REFRESH_DISABLE=1

How It Works and Merge Rules

On startup, the plugin locates the @deepseek-ai/dsh-llm-pi-ai package referenced by the dsh CLI process, then locates the dist/models.generated.js file in the @earendil-works/pi-ai package, directly replaces the MODELS[provider] mappings, and writes a header to trigger re-resolution.

Data Sources and Authentication

The plugin supports the following data sources:
- OpenRouter: full details (pricing, context, max tokens, etc.).
- OpenCode Zen, Fireworks, Groq, Together, DeepSeek: returns only ID lists.

Authentication uses environment variables (such as FIREWORKS_API_KEY, GROQ_API_KEY) or credential records stored on DSH’s model pages (llm-pi-ai/<provider>). If a key is missing, the source is skipped and the installed catalog remains unchanged.

Merge Strategy

  • OpenRouter: Live entries win (price, context, max tokens, etc.), while curated fields (compatibility, cost, protocol) retain the values from installed entries.
  • ID list sources: Curated fields (compatibility, cost, protocol, protocol) from installed entries are preserved, while structural fields (context window, max tokens, name) are updated. Unknown IDs are added with default values. Non-chat entries are discarded.

Fetched lists are cached under $DSH_HOME/catalog-refresh/, so restarts can apply the last valid refresh even without network access.

Reasoning Effort Level Support

dsh-llm-pi-ai shows the reasoning effort selector only when a model declares effort metadata. This plugin injects thinkingLevelMap by default for rebuilt reasoning models based on the CATALOG_REFRESH_EFFORTS configuration. By default, reasoning models provide Off/High/Max levels, while non-reasoning models do not.

For ID list sources, known IDs retain the capability flags from installed entries, while unknown IDs are treated as having reasoning capability by default. Fireworks reasoning models are routed through native endpoints to avoid budget validation errors.

Use Cases and Notes

This plugin is suitable for DSH users who need immediate access to the latest model lists.

  • The plugin runs with the permissions of the current DSH process; ensure you have reviewed its source code and license.
  • The plugin depends on the @deepseek-ai/cordis dependency.

For more information, see the GitHub repository.