One invalid reasoningEfforts key deregisters the whole provider (NO_ADAPTER), and --dump-config does not catch it

[monmacllc]

Version: @deepseek-ai/dsh 0.2.2-rc.1, Linux x64, Node 24.22.2. Profile: web/headless, custom OpenAI-compatible provider via llm-pi-ai.

What happened
In cordis.patch.yml I declared reasoning levels with my own names:

- id: llm-pi-ai
  config:
    providers:
      venice:
        apiKeyEnv: VENICE_API_KEY
        api: openai-completions
        baseURL: https://api.venice.ai/api/v1
        models:
          - id: some-model
            reasoningEfforts:
              mechanical: low
              reasoning: medium

dsh --profile headless --dump-config composed the profile without complaint and printed the levels. The first real run then failed:

llm-pi-ai (@deepseek-ai/dsh-llm-pi-ai): ValidationError: invalid config:
  - $.providers.venice.models[0].reasoningEfforts expected false | { [key: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"]: string | ... }
dsh: NO_ADAPTER: no adapter registered for provider "venice"

Why this is three defects, not one

1. One invalid field in one model entry deregisters the adapter for the entire provider: every model on that provider becomes unusable, not just the one with the bad key.
2. --dump-config composes but does not validate, so the only way to discover the error is a live request.
3. The user-facing error (NO_ADAPTER ... provider "venice") names the wrong layer; the ValidationError above it is the real cause and is easy to miss in a log.

Expected

• Validate per field at load; reject (or skip) the offending model entry and keep the provider's other models registered.
• --dump-config (or a --check-config) should fail with the same ValidationError so profiles can be verified without spending a request.
• The docs' "Each key is a level the menu offers" reads as if keys are free-form; a one-line note that keys are restricted to off|minimal|low|medium|high|xhigh|max would have prevented this.

Workaround
Use the fixed key names (low: low, medium: medium) and finish every profile change with a real dsh headless "..." call.

[argszero]

All three of your points hold, and the first is worse than you wrote. Everything below is read in the tree at e8f7b93a34 (dsh-v0.2.2-rc.2, the current head), so it is measured one release later than the 0.2.2-rc.1 you filed on, not against it.

1. The blast radius is the plugin, not the provider

The key side is a closed set: packages/llm/llm-pi-ai/src/config.ts:326-330 types each key as z.union(THINKING_LEVELS), and packages/llm/llm-pi-ai/src/catalog.ts:75-86 holds those seven behind a compile-time drift gate — an upstream upgrade that adds or removes a level fails to compile here instead of silently narrowing what a profile may write. So mechanical is rejected by the key schema, exactly as your error says.

Why that costs everything: reasoningEfforts is validated by schemastery as part of the plugin's config object, while registration is one adapter for all routes at once — packages/llm/llm-pi-ai/src/index.ts:331 calls ctx.llm.registerAdapter(routes, adapter) where routes is every provider key (:323). There is no per-provider registration to survive the failure. When the config fails validation the plugin never reaches apply(), so nothing registers at all, and every provider llm-pi-ai serves is gone — not just venice, and not just that one model. Your NO_ADAPTER ... "venice" is one symptom of a registration that never happened.

Where that message is built: packages/llm/llm/src/index.ts:1037 produces no adapter registered for provider "${provider}" with the code from packages/llm/llm/src/error.ts:51. It is literally true and causally useless — it reports the absence while the ValidationError above it reports the cause. Your point 3 is a real defect, not a wording preference.

2. --dump-config composes; it never mounts

The CLI's own help says it: apps/cli/src/args.ts:171 — "print the composed profile tree and exit". And apps/cli/src/dump-config.ts:3-4 states the mechanism: compose the patch layers "without booting or evaluating !!js". runDumpConfig (:32-43) prepares the profile and calls renderConfigDump; no plugin is mounted, so no plugin's config schema is ever consulted. The product already admits the consequence in the schema description at packages/boot/app-boot/src/config-schema/document.ts:158: the dump prints the parsed entry list, and "plugin startup checks ... still require runtime validation".

So the dump is not buggy — it does what it promises. What does not exist is the second verb you asked for.

One arm you may not know: --dump-config --default-only omits the user layer and overlays, and is documented as "the recovery diagnostic for a broken cordis.patch.yml, which is then never parsed" (dump-config.ts:26-28). It validates nothing either, but it separates a break in your layer from one in the shipped layers.

3. The key set is ours to constrain. The value column is yours.

This is the part your report does not raise, and it changes the fix for your immediate problem.

reasoningEfforts has two columns and only one is closed. The schema's own comment says it — config.ts:316-325: "Keys are the offered levels, values their wire spellings." The key is a selector label the model picker offers; the value is the exact spelling dispatch puts on the wire. packages/llm/llm-pi-ai/README.md:107 states the same thing: "each key is a level selectors offer, its value the spelling dispatch sends on the wire, so max: ultra renames a level for a gateway with its own vocabulary."

Which means your config is inverted. You wrote

reasoningEfforts:
  mechanical: low
  reasoning: medium

putting your gateway's names in the key position. A gateway with its own vocabulary is what the value position is for:

reasoningEfforts:
  low: mechanical
  medium: reasoning

That is the documented max: ultra shape, and it is why the closed key set costs you nothing. Two constraints survive it: only off may leave its value empty, and a set offering no level beyond off is refused (catalog.ts:743-762).

So the vocabulary is ours on the selector side — it is the product's menu, and the picker has to render it — and not ours on the wire side, where it is unconstrained by design.

4. Your docs point is right, and the sentence already exists one layer over

llm-pi-ai/README.md:107 describes the two columns without ever saying the key side is a closed list. The settings-UI documentation does say it — packages/client/ui-settings-models/README.md:66: a level select over "the keys llm-pi-ai's configuration schema accepts in reasoningEfforts, read from the namespace schema like the protocol choices and today off, minimal, low, medium, high, xhigh, and max, each usable once", paired with the API value sent for it.

Someone editing cordis.patch.yml reads the adapter README, not the settings-UI README. One sentence added there — closed set, read from the schema, value column carries the wire spelling — would have prevented this report, and the wording already exists to copy.

5. Restart or runtime? Restart.

You did not ask, and it decides what you do next.

The adapter does re-register without a restart when the route set changes: index.ts:339 binds loader/volatile-update to ensureRegistrationFacts(), whose comment (:317-322) says the swap is atomic and "returning to a working configuration always re-applies"; packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts:215 drives the reverse — a route added from settings, dropped on reset, and the request then failing with NO_ADAPTER.

But that path lives inside apply(), for a mounted plugin receiving a new route set. A config that fails schema validation never gets there: the ValidationError is raised before apply() runs, so there is no mounted instance to receive a later update. That is read from the source, not measured — I did not restart a process to watch it. If your edit corrects the config, plan on a fresh process.

6. Your two asks

Closed set in the docs: yes — §4, one sentence, in the file a YAML author actually reads.

--check-config: the right shape, but it is a new verb, not a flag on the existing one. It needs to mount the profile's plugins far enough to run their config schemas without starting them; --dump-config cannot become that without breaking what it promises, since composing a tree that never boots is its whole value. That one belongs to the maintainers to schedule.

I hold no upstream pull-request channel here — this repository's issues and pull requests are closed to outside contribution — so I can measure this and describe the change, and it reaches the code through them. If you want point 1 tracked as a defect rather than a fix request, the sharpest statement is: validation is per-plugin while registration is one adapter for every route, so no granularity exists at which one bad model entry could cost only that model.