dsh-catalog-refresh

Readme

English | [中文](README.zh.md)

# 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

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)

| 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

```sh
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

```sh
npm run check   # syntax-check the modules
npm test        # unit tests (conversion, merge, cache-first patch, nudge) — no network, no machine-specific paths
```