dsh-autofill-model-metadata

Fill a DSH gateway route's model metadata (name, contextWindow, maxTokens, input, reasoningEfforts) from the models.dev catalog — using only the mappings you declare by hand.

This is a port of the pi-autofill-model-metadata Pi extension: the same explicit-mapping philosophy, moved onto the DSH settings seam.

Why explicit mapping

DSH has no native metadata filling. The plugins that do it fall into two camps: provider-level refresh (dsh-models-dev: sources: { route: <models.dev-provider> }) and loose name matching. Both guess. This plugin refuses to:

• You write down, per route and per local model id, exactly which models.dev model it is: mapping.<route>.<localModelId> = "<modelsDevProvider>/<modelsDevModel>".
• No fuzzy match, no case folding across providers, no searching another provider when a lookup fails.
• Anything unmapped, unknown, or ambiguous is a refusal, not a guess. A route whose plan refuses is not written at all — you never get a half-filled array.

Declared fields always win: the plugin only fills fields the profile leaves undefined.

Install

Requires DSH >= 0.2.0-rc.2. From the plugin checkout:

DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$DSH" plugin --profile desktop add link:/absolute/path/to/dsh-autofill-model-metadata

Then restart DSH Desktop (plugins mount at startup).

Configure

The config accepts these fields (the graphical page edits the mapping, the rest stays in the settings document):

{
  "mapping": {
    // route name as it appears in Settings → Models
    "my-gateway": {
      // local model id on the wire  ->  models.dev provider/model
      "claude-opus-4-5": "anthropic/claude-opus-4-5",
      "gemini-3-pro": "google/gemini-3-pro-preview"
    }
  },
  "modelsDevUrl": "https://models.dev/api.json",
  "cacheTTLHours": 24,
  "applyOnStart": true,
  "dryRun": false,
  "requireCompleteMapping": true,
  "builtinSettingsForm": "auto"
}

field	default	meaning
mapping	{}	the declared table; empty means the plugin does nothing at all
modelsDevUrl	https://models.dev/api.json	catalog endpoint
cachePath	$DSH_HOME/plugins/dsh-autofill-model-metadata/models.dev.json	catalog cache
cacheTTLHours	24	cache lifetime; 0 refetches every time
applyOnStart	true	apply once when the plugin mounts
dryRun	false	plan and log, write nothing
requireCompleteMapping	true	undeclared models on a mapped route are an error
builtinSettingsForm	"auto"	auto / always / never — see Settings

Manual run, from any local browser session (<port> is the DSH web server):

BASE=http://127.0.0.1:<port>/api/dsh-autofill-model-metadata
curl -X POST $BASE/apply   -H 'content-type: application/json' -d '{}'   # {"route":"..."} to narrow
curl $BASE/status                                                        # mapping state, no catalog fetch
curl $BASE/inspect                                                       # same, resolved against the catalog
curl "$BASE/catalog?q=gpt-5.4&limit=10"                                  # candidate mapping targets
curl -X POST $BASE/mapping -H 'content-type: application/json' \
  -d '{"mapping":{"my-route":{"fast-model":"openai/gpt-5.4"}},"apply":true}'

Every endpoint is loopback-only and answers 403 to anything else; /apply, /mapping and /page-live are POST, the rest are GET.

/mapping answers 200 once the write lands, even when a requested fill is then refused: the mapping really was saved, and a failed pass is reported separately in applyError rather than disguised as a failed save. /status and /inspect answer with the mapping read from the settings document, not from the volatile copy the loader refreshes a moment after a write.

Settings

The plugin ships a graphical settings page, and it also honours the host's autoGenerate flag for the schema above — so a host that renders generated forms, now or in a later version, keeps showing one whenever this page is not there.

builtinSettingsForm	behaviour
"auto" (default)	the generated form stays available until the browser half loads and reports in (POST /page-live)
"always"	the generated form is never suppressed
"never"	the generated form is suppressed as soon as the plugin mounts

true/false are accepted as aliases for always/never.

What "the original form" means in 0.2.0-rc.2. It is worth being exact here: the shipped client contains no generic schema-driven form renderer at all. Every official settings page (Models, Shell, Agent loop, …) is a hand-written companion package, and autoGenerate is carried by the settings transport but consumed by nothing yet. So on this version the surfaces for a plugin config are:

1. this page, when its bundle loads;
2. the profile's own configuration document, always — hand-editable, and the thing the page writes back to;
3. a generated form, on any host that starts rendering one.

The auto policy is what keeps (3) honest: it does not suppress the flag until the page has actually reported in, so a page that never loads never costs you a surface. The page's own failure banner says the same thing when its host endpoints are unreachable.

The page appears as Settings → Model metadata. It lists only relevant routes — a route the profile configures, or one that appears in the mapping — so the dozens of providers the host advertises but nobody configured cannot bury the ones that matter. A mapped route the host does not offer is still listed, with its reason, so a typo cannot hide. Each card shows: every declared model, the fields it declares by hand (never overwritten), what a pass would fill, the mapping source in an editable field with catalog search, and the refusals that would apply. Save mapping writes the whole table in one revision-fenced op; Save and fill does that and runs a pass. Nothing is written until you save, unsaved edits survive a reload, and a dry run or an already-complete route is reported as exactly that rather than as a fill.

Both the page and the config document end up in the same settings service. The page reads the settings revision along with its state and sends it back when saving, so an edit made in the config document while the page sat open makes the save fail closed — the page is told the mapping moved and to reapply — rather than replacing the whole table with what the page happened to be showing. A fill pass re-reads and re-plans the route inside the same fence, so a model added by hand between planning and writing is never dropped: the pass refuses instead. Without a revision from the caller there is nothing to compare against, so the freshest one is used and the write proceeds.

What gets filled

local field	from models.dev	rule
name	model.name
contextWindow	limit.context	written only when > 0
maxTokens	limit.output	written only when > 0
input	modalities.input	image present → ['text','image']
reasoningEfforts	reasoning_options (effort values)	see below

reasoningEfforts follows the pi-ai schema, where a map containing only off is invalid:

• effort values present → map them, including none → off;
• only off usable, or reasoning: false → false;
• catalog says nothing → field left absent, so the profile's own default stands.

A model is eligible only when tool_call === true and status !== 'deprecated'. Eligibility is checked but never written — the plugin does not flip tool_call.

Refusals

Per route, all-or-nothing. A refused route writes nothing.

kind	when
malformed-source	the mapping value is not provider/model
unknown-provider	that provider id is not in the catalog
unknown-model	that model id is not under that provider
ambiguous-source	several catalog models match case-insensitively
not-agent-capable	matched model cannot call tools, or is deprecated
missing-mapping	requireCompleteMapping and a route model is undeclared
undeclared-mapping	a mapping points at a model the route does not configure

undeclared-mapping fires even with requireCompleteMapping: false, so a typo in a local id is never silently ignored.

Design notes

• One atomic write per route: a single set op at ['providers', <route>, 'models'], fenced by the revision re-read immediately before mutate. Routes are independent — one refusal does not block another.
• Inert when unmapped: with mapping: {} there is no catalog fetch, no cache write, no settings read.
• Offline tolerant: a failed fetch falls back to the cached catalog and logs; a stale cache is used rather than refusing.
• User layer wins: the merge base is the settings user layer when present.

Development

pnpm install
pnpm run verify     # tsc --noEmit && tsdown && vitest

verify runs the whole suite: unit tests per module, a composition test driving apply() against a stub host, a contract test validating planned output against the real @deepseek-ai/dsh-llm-pi-ai@0.2.0-rc.2 schema (it skips itself if that package is absent), render tests for the settings page, and a client-bundle test that loads the built lib/client.js through a stub window.__ModuleLoader__ with the same seeded modules the shell provides.

Two halves

half	entry	output	loaded by
host	src/index.ts	lib/index.mjs (ESM)	the DSH Loader, via the cordis.patch.yml row
browser	src/client/index.tsx	lib/client.js (CJS + window.__ModuleLoader__ banner)	the Web shell, via dsh.client in package.json

react and react/jsx-runtime are external and resolved by the shell's module seed — bundling a second React would break hooks. The page deliberately imports no Harness Client package: shared UI modules change without notice, so it carries its own controls (buttons, tags, checkbox, inputs) styled only with --dsw-alias-* theme tokens, matching the shipped settings pages. The bundle id must stay the package name: it is the cache key the loader serves at /plugins/<package>/client.js.

Client-only changes need the shell to re-read the bundle: a rebuild is enough while the client-plugin HMR receiver is active, otherwise reload the page (the loader cache-busts on the bundle's revision), or restart DSH Desktop.

macOS: vitest cannot start under the DSH runtime node

The node shipped with DSH Desktop is signed with the hardened runtime, while rollup's native binary is ad-hoc signed. macOS refuses the load (ERR_DLOPEN_FAILED, "mapping process and mapped file (non-platform) have different Team IDs"), so vitest dies before collecting. Re-sign a copy of node ad-hoc and run the suite with it:

mkdir -p .devnode && cp "$(command -v node)" .devnode/node
codesign --force --sign - .devnode/node
PATH="$PWD/.devnode:$PATH" pnpm run verify

.devnode/ is git-ignored. This affects any project in this environment that runs vitest, including dsh-deep-sleep.

Releasing

Releases publish from the release workflow on a version tag:

git tag v0.1.0
git push origin v0.1.0

The workflow uses npm Trusted Publishing (OIDC, id-token: write), so no NPM_TOKEN secret is stored. npm refuses to attach a trusted publisher to a package that does not exist yet, so the first release has to be published once from a logged-in machine (npm login && npm publish); afterwards attach the publisher at the package's npm Settings → Trusted publishing page with this repository and release.yml, and later tags publish without a token. The publish step skips versions already on the registry, so re-pushing a tag is safe.

Limitations

• Reads models.dev only; no other metadata source.
• Never invents a mapping: unmapped models stay untouched.
• Does not touch tool_call, status, cost, or compat.
• Applies on mount and on config edit; there is no scheduled refresh — use the apply endpoint or restart to force one.