@askdkc/dsh-cli 0.12.1 → 0.12.3

package/README.md

@@ -42,7 +42,7 @@ This is dkc's independently developed fork of [dsh-TUI by chimney](https://githu
 Requires [Node.js](https://nodejs.org/en) `^22.19 || >=24`, pnpm 11, a
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) source
 checkout with dependencies installed, and `DEEPSEEK_API_KEY`. We aim to support
-the latest DSH release. The primary validated Harness version is `0.2.0-rc.1`;
+the latest DSH release. The primary validated Harness version is `0.2.0-rc.2`;
 older supported versions are listed in [ADAPTER.md](ADAPTER.md).
 
 Clone recursively to fetch submodules. In an existing checkout, run
@@ -57,7 +57,7 @@ node scripts/with-publish-manifest.mjs npm pack --ignore-scripts
 TARBALL="$PWD/askdkc-dsh-cli-$(node -p "require('./package.json').version").tgz"
 
 cd ~/DIR/TO/deepseek-harness
-pnpm dsh plugin --profile dsh-cli add "$TARBALL"
+pnpm dsh plugin --profile dsh-cli add "@askdkc/dsh-cli@file:${TARBALL}"
 pnpm dsh --profile dsh-cli
 ```
 
@@ -65,6 +65,11 @@ Replace `~/DIR/TO/deepseek-harness` with your checkout path. The first interacti
 launch registers `dsh-cli`; open a new shell, then run it from your project directory.
 To update this fork, rebuild and reinstall the tarball. `/update` uses the registry.
 
+Use the named `@askdkc/dsh-cli@file:...` form for local tarball updates. A bare
+tarball path can fail with `ENOENT` when pnpm resolves a previous `file:` dependency
+whose archive has been deleted. `TARBALL` holds the archive's absolute path; pass
+it to the install command instead of executing it.
+
 For PATH setup and install issues, see [Getting started](docs/getting-started.en.md).
 
 ## Use

package/lib/types/dsh-adapter/contract.d.ts

@@ -1,9 +1,10 @@
 /** Primary validated upstream line (newest). */
-export declare const UPSTREAM_VALIDATED_VERSION = "0.2.0-rc.1";
+export declare const UPSTREAM_VALIDATED_VERSION = "0.2.0-rc.2";
 /**
  * Explicitly supported upstream prerelease lines, oldest first.
  *
- * 0.2.0-rc.1 = primary continuous-CI line; 0.1.7-rc.2/rc.1 = previous
+ * 0.2.0-rc.2 = primary continuous-CI line; 0.2.0-rc.1 = previous primary;
+ * 0.1.7-rc.2/rc.1 = previous
  * build (mapped compatibility); 0.1.5-rc.1/alpha.2/alpha.1 = mapped
  * compatibility lines (source-checked when the primary line moves);
  * 0.1.3-alpha.2 = compatibility line (the only 0.1.3 build on npm);
@@ -16,7 +17,7 @@ export declare const UPSTREAM_VALIDATED_VERSION = "0.2.0-rc.1";
  * The peer range in package.json is deliberately wider than this list: an
  * install on an older or newer line is allowed but reports drift at boot.
  */
-export declare const UPSTREAM_VALIDATED_VERSIONS: readonly ["0.1.0-rc.6", "0.1.0-rc.7", "0.1.0-rc.8", "0.1.1-rc.1", "0.1.1-rc.2", "0.1.2-alpha.3", "0.1.2-alpha.4", "0.1.2-alpha.5", "0.1.2-rc.1", "0.1.3-alpha.2", "0.1.5-alpha.1", "0.1.5-alpha.2", "0.1.5-rc.1", "0.1.7-rc.1", "0.1.7-rc.2", "0.2.0-rc.1"];
+export declare const UPSTREAM_VALIDATED_VERSIONS: readonly ["0.1.0-rc.6", "0.1.0-rc.7", "0.1.0-rc.8", "0.1.1-rc.1", "0.1.1-rc.2", "0.1.2-alpha.3", "0.1.2-alpha.4", "0.1.2-alpha.5", "0.1.2-rc.1", "0.1.3-alpha.2", "0.1.5-alpha.1", "0.1.5-alpha.2", "0.1.5-rc.1", "0.1.7-rc.1", "0.1.7-rc.2", "0.2.0-rc.1", "0.2.0-rc.2"];
 /**
  * Framework packages version on their own lines; the contract validates
  * their MAJOR (breaking surface), not the harness prerelease number.

package/lib/types/dsh-adapter/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/contract.ts"],"names":[],"mappings":"AAkBA,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,eAAe,CAAA;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,6PAiB9B,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5D,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,o8BA+B5B,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAUD,4EAA4E;AAC5E,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/D,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,MAAM,CAAC,CAAA;AAEvG,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAKlG;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAQxF;AAkBD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,QAA6D,CAAA;AAYlG,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAqB9E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAE9F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,MAAM,EAAE,CAQV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,kBAAkB,EAAE,CAuBtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,iBAAiB,CAAA;IACvB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,oBAAoB,GAAG,SAAS,CA0BlC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/contract.ts"],"names":[],"mappings":"AAkBA,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,eAAe,CAAA;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,2QAkB9B,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5D,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,o8BA+B5B,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAUD,4EAA4E;AAC5E,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/D,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,MAAM,CAAC,CAAA;AAEvG,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAKlG;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAQxF;AAkBD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,QAA6D,CAAA;AAYlG,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAqB9E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAE9F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,MAAM,EAAE,CAQV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,kBAAkB,EAAE,CAuBtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,iBAAiB,CAAA;IACvB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,oBAAoB,GAAG,SAAS,CA0BlC"}

package/lib/types/dsh-adapter/contract.js

@@ -2,7 +2,7 @@
  * Upstream compatibility contract.
  *
  * The TUI is validated against a set of upstream prerelease lines — the
- * current primary (0.2.0-rc.1) plus older lines kept in backward
+ * current primary (0.2.0-rc.2) plus older lines kept in backward
  * compatibility across the 0.1.5, 0.1.3, 0.1.2, 0.1.1 and 0.1.0 release
  * families.
  * Every official package this adapter touches is blessed here; anything
@@ -16,11 +16,12 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 /** Primary validated upstream line (newest). */
-export const UPSTREAM_VALIDATED_VERSION = '0.2.0-rc.1';
+export const UPSTREAM_VALIDATED_VERSION = '0.2.0-rc.2';
 /**
  * Explicitly supported upstream prerelease lines, oldest first.
  *
- * 0.2.0-rc.1 = primary continuous-CI line; 0.1.7-rc.2/rc.1 = previous
+ * 0.2.0-rc.2 = primary continuous-CI line; 0.2.0-rc.1 = previous primary;
+ * 0.1.7-rc.2/rc.1 = previous
  * build (mapped compatibility); 0.1.5-rc.1/alpha.2/alpha.1 = mapped
  * compatibility lines (source-checked when the primary line moves);
  * 0.1.3-alpha.2 = compatibility line (the only 0.1.3 build on npm);
@@ -50,6 +51,7 @@ export const UPSTREAM_VALIDATED_VERSIONS = [
     '0.1.7-rc.1',
     '0.1.7-rc.2',
     '0.2.0-rc.1',
+    '0.2.0-rc.2',
 ];
 /**
  * Framework packages version on their own lines; the contract validates

package/node_modules/@askdkc/dsh-auth/README.ja.md

@@ -119,6 +119,12 @@ dsh plugin --profile <name> add @askdkc/dsh-auth
   （`llm-pi-ai` の設定プロファイルなど）、レジストリはそのルートの登録を拒否します。
   プラグインは拒否をログに記録し、残りのルートを登録します。
   1 つのプロバイダーには 1 つのアダプターを割り当ててください。
+- `opencode` / `opencode-go` は、インストール済み pi-ai カタログの上に
+  Zen の最新モデル一覧を提供します（モデルごとの通信プロトコルは最も近い
+  カタログの兄弟モデルから解決し、既存モデルは常に優先されるため、追加のみで
+  削除は起きません）。`pnpm --dir dsh-auth sync:models` でスナップショットを
+  更新できます（`models.dev` と Zen の `/v1/models` を参照）。
+  実行時にネットワークは使いません。
 
 ## セキュリティ上の注意
 

package/node_modules/@askdkc/dsh-auth/README.md

@@ -118,6 +118,11 @@ the `/auth login <provider>` hint — never silently.
   profile naming the same provider — is refused by the registry; the plugin
   logs the refusal and mounts the remaining routes. Keep one provider on one
   adapter.
+- `opencode` / `opencode-go` serve the live Zen roster on top of the installed
+  pi-ai catalog (per-model wire protocols resolve from the nearest catalog
+  sibling; installed models always win). Refresh the checked-in snapshot with
+  `pnpm --dir dsh-auth sync:models` (reads `models.dev` plus the live Zen
+  `/v1/models` rosters); runtime stays offline-safe.
 
 ## Security notes
 

package/node_modules/@askdkc/dsh-auth/lib/fresh-models.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fresh OpenCode rosters on top of the installed pi-ai catalog.
+ *
+ * The installed catalog is the wire authority (per-model `api` protocol,
+ * base URLs, compat): overlapping ids are served untouched. The checked-in
+ * snapshot (`opencode-snapshot.generated.ts`, refreshed from models.dev plus
+ * the live Zen `/v1/models` rosters) contributes only roster ids the
+ * installed catalog lacks — each synthesized with per-model protocol
+ * resolution, never a route-level default:
+ *
+ * - models.dev metadata (name, reasoning, modalities, limits, cost) plus the
+ *   wire envelope (`api`, `baseUrl`, `compat`, thinking levels, image
+ *   budgets) inherited from the nearest same-route catalog sibling;
+ * - ids neither source describes are cloned wholesale from that sibling and
+ *   keep working wherever the sibling does (provenance lives in the
+ *   snapshot, not on the model object).
+ *
+ * The merge only ever adds: the result always covers the installed catalog,
+ * so a stale snapshot delays additions but can never remove working models.
+ *
+ * @module dsh-auth/fresh-models
+ */
+import type { PiAiProvider } from './pi-ai.js';
+/** One allowlisted models.dev entry (see scripts/sync-opencode-models.mjs). */
+export interface FreshModelEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly reasoning?: boolean;
+    readonly attachment?: boolean;
+    readonly modalities: {
+        readonly input: readonly string[];
+    };
+    readonly limit: {
+        readonly context: number;
+        readonly output?: number;
+    };
+    readonly cost: {
+        readonly input: number;
+        readonly output: number;
+        readonly cache_read?: number;
+    };
+    readonly temperature?: boolean;
+    readonly reasoning_options?: {
+        readonly effort: readonly string[];
+    };
+}
+export type FreshRouteId = 'opencode' | 'opencode-go';
+/**
+ * Union the snapshot roster onto one catalog provider. Installed models win
+ * on conflict and classifier-roster ids stay on pi-ai's classifier path, so
+ * the merged list always covers the installed catalog — a stale snapshot
+ * delays additions but never removes a working model.
+ * @param catalog - the installed pi-ai catalog provider for one route.
+ * @param route - the route the snapshot section is keyed under.
+ * @returns the catalog provider, or a shallow clone serving the union.
+ */
+export declare function withFreshModels(catalog: PiAiProvider, route: FreshRouteId): PiAiProvider;
+/** Snapshot roster ids for one route, for smoke coverage. */
+export declare function freshRosterIds(route: FreshRouteId): readonly string[];

package/node_modules/@askdkc/dsh-auth/lib/fresh-models.js

@@ -0,0 +1,246 @@
+import { OPENCODE_SNAPSHOT } from './opencode-snapshot.generated.js';
+function record(value, what) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`dsh-auth: snapshot ${what} is not an object`);
+    }
+    return value;
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function boundedStringList(value, what, max) {
+    if (!Array.isArray(value) || value.length > max || !value.every(item => typeof item === 'string')) {
+        throw new Error(`dsh-auth: snapshot ${what} is not a string list`);
+    }
+    const list = value;
+    if (new Set(list).size !== list.length)
+        throw new Error(`dsh-auth: snapshot ${what} has duplicates`);
+    return list;
+}
+function positiveInt(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function nonnegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function parseEntry(route, key, value) {
+    const row = record(value, `${route}/${key}`);
+    if (row.id !== key)
+        throw new Error(`dsh-auth: snapshot ${route}/${key} names "${String(row.id)}"`);
+    const name = nonEmptyString(row.name);
+    if (name === undefined)
+        throw new Error(`dsh-auth: snapshot ${route}/${key} has no name`);
+    const modalities = record(row.modalities ?? fail(route, key, 'modalities'), `${route}/${key} modalities`).input;
+    if (!Array.isArray(modalities) || modalities.length === 0 || !modalities.every(m => typeof m === 'string')) {
+        throw new Error(`dsh-auth: snapshot ${route}/${key} has no input modalities`);
+    }
+    const limit = record(row.limit ?? fail(route, key, 'limit'), `${route}/${key} limit`);
+    const context = positiveInt(limit.context);
+    if (context === undefined)
+        throw new Error(`dsh-auth: snapshot ${route}/${key} has no context limit`);
+    const output = limit.output === undefined ? undefined : positiveInt(limit.output);
+    if (limit.output !== undefined && output === undefined) {
+        throw new Error(`dsh-auth: snapshot ${route}/${key} has a malformed output limit`);
+    }
+    const cost = record(row.cost ?? fail(route, key, 'cost'), `${route}/${key} cost`);
+    const input = nonnegativeNumber(cost.input);
+    const outputCost = nonnegativeNumber(cost.output);
+    if (input === undefined || outputCost === undefined) {
+        throw new Error(`dsh-auth: snapshot ${route}/${key} has no pricing`);
+    }
+    const cacheRead = cost.cache_read === undefined ? undefined : nonnegativeNumber(cost.cache_read);
+    if (cost.cache_read !== undefined && cacheRead === undefined) {
+        throw new Error(`dsh-auth: snapshot ${route}/${key} has malformed cache pricing`);
+    }
+    const entry = {
+        id: key,
+        name,
+        reasoning: typeof row.reasoning === 'boolean' ? row.reasoning : undefined,
+        attachment: typeof row.attachment === 'boolean' ? row.attachment : undefined,
+        temperature: typeof row.temperature === 'boolean' ? row.temperature : undefined,
+        reasoning_options: parseEffort(route, key, row.reasoning_options),
+        modalities: { input: modalities.slice() },
+        limit: output === undefined ? { context } : { context, output },
+        cost: cacheRead === undefined ? { input, output: outputCost } : { input, output: outputCost, cache_read: cacheRead },
+    };
+    return entry;
+}
+function parseEffort(route, key, value) {
+    if (value === undefined)
+        return undefined;
+    const options = record(value, `${route}/${key} reasoning options`).effort;
+    if (options === undefined)
+        return undefined;
+    if (!Array.isArray(options) || !options.every(v => typeof v === 'string')) {
+        throw new Error(`dsh-auth: snapshot ${route}/${key} has malformed effort values`);
+    }
+    return { effort: options.slice() };
+}
+function fail(route, key, what) {
+    throw new Error(`dsh-auth: snapshot ${route}/${key} has no ${what}`);
+}
+function parseRoute(route, value) {
+    const row = record(value, route);
+    const roster = boundedStringList(row.roster, `${route} roster`, 500);
+    if (roster.some(id => id.length === 0))
+        throw new Error(`dsh-auth: snapshot ${route} roster has an empty id`);
+    const entriesRaw = record(row.entries ?? {}, `${route} entries`);
+    const entries = {};
+    for (const key of Object.keys(entriesRaw))
+        entries[key] = parseEntry(route, key, entriesRaw[key]);
+    const fallback = boundedStringList(row.fallback ?? [], `${route} fallback`, 500);
+    return { roster, entries, fallback };
+}
+/** Validate the checked-in snapshot once; a malformed file is a boot error. */
+function parseSnapshotData(input) {
+    const root = record(input, 'root');
+    if (root.version !== 1)
+        throw new Error('dsh-auth: snapshot has an unsupported version');
+    if (nonEmptyString(root.generatedAt) === undefined)
+        throw new Error('dsh-auth: snapshot has no timestamp');
+    return {
+        version: 1,
+        generatedAt: root.generatedAt,
+        piAiVersion: nonEmptyString(root.piAiVersion) ?? 'unknown',
+        classifiers: boundedStringList(root.classifiers ?? [], 'classifiers', 500),
+        opencode: parseRoute('opencode', root.opencode),
+        'opencode-go': parseRoute('opencode-go', root['opencode-go']),
+    };
+}
+const SNAPSHOT = parseSnapshotData(OPENCODE_SNAPSHOT);
+/** Length of the id prefix two models share (`a-b` vs `a-c` share 2). */
+function sharedPrefixLength(a, b) {
+    const end = Math.min(a.length, b.length);
+    let length = 0;
+    while (length < end && a[length] === b[length])
+        length += 1;
+    return length;
+}
+/** Wire protocols, most universal first, for deterministic sibling choice. */
+function apiRank(api) {
+    if (api === 'openai-completions')
+        return 0;
+    if (api === 'openai-responses')
+        return 1;
+    if (api === 'anthropic-messages')
+        return 2;
+    if (api === 'google-generative-ai')
+        return 3;
+    return 4;
+}
+/**
+ * Nearest same-route catalog sibling: longest shared id prefix wins, then
+ * the most universal wire protocol, then alphabetical order. Documented
+ * approximation, fully deterministic — the same snapshot and catalog always
+ * resolve the same wire envelope.
+ */
+function nearestSibling(catalog, id) {
+    let best = catalog[0];
+    if (best === undefined)
+        throw new Error('dsh-auth: installed catalog is empty');
+    for (const candidate of catalog) {
+        const prefix = sharedPrefixLength(candidate.id, id);
+        const bestPrefix = sharedPrefixLength(best.id, id);
+        if (prefix > bestPrefix
+            || (prefix === bestPrefix && apiRank(candidate.api) < apiRank(best.api))
+            || (prefix === bestPrefix && apiRank(candidate.api) === apiRank(best.api) && candidate.id < best.id)) {
+            best = candidate;
+        }
+    }
+    return best;
+}
+/** pi-ai thinking levels; `off` is always unsupported, the rest map to themselves. */
+const THINKING_LEVELS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+function thinkingLevels(effort, sibling) {
+    const siblingMap = (sibling.thinkingLevelMap ?? {});
+    const levels = new Set(effort);
+    // Only narrow the sibling envelope when every effort value it names fits
+    // inside it; otherwise the sibling map stands (documented approximation).
+    if (![...levels].every(level => Object.hasOwn(siblingMap, level)))
+        return sibling.thinkingLevelMap;
+    const map = { off: null };
+    for (const level of THINKING_LEVELS) {
+        if (!Object.hasOwn(siblingMap, level))
+            continue;
+        map[level] = levels.has(level) ? level : null;
+    }
+    return map;
+}
+/**
+ * Resolve one snapshot roster id to a pi-shaped model: wire envelope from
+ * the sibling, display metadata and capacity from models.dev. pi-ai drops
+ * video/pdf/audio modalities (text/image only) and never discloses
+ * cache-write pricing, so both are inherited or omitted — see field notes.
+ */
+function synthesize(catalog, route, id, entry) {
+    const sibling = nearestSibling(catalog, id);
+    // Same-route sibling, so its provider id is already the route's own.
+    if (entry === undefined)
+        return { ...sibling, id, name: id };
+    const modalities = new Set(entry.modalities.input);
+    if (!modalities.has('text')) {
+        throw new Error(`dsh-auth: snapshot ${route}/${id} has no text modality`);
+    }
+    const compat = entry.temperature === false
+        ? { ...sibling.compat, supportsTemperature: false }
+        : sibling.compat;
+    const input = modalities.has('image') ? ['text', 'image'] : ['text'];
+    return {
+        ...sibling,
+        id,
+        name: entry.name,
+        reasoning: entry.reasoning ?? sibling.reasoning,
+        input: [...input],
+        cost: {
+            input: entry.cost.input,
+            output: entry.cost.output,
+            cacheRead: entry.cost.cache_read ?? sibling.cost.cacheRead ?? 0,
+            cacheWrite: sibling.cost.cacheWrite ?? 0,
+        },
+        contextWindow: entry.limit.context,
+        maxTokens: entry.limit.output ?? sibling.maxTokens,
+        compat,
+        thinkingLevelMap: entry.reasoning === false
+            ? undefined
+            : entry.reasoning_options === undefined
+                ? sibling.thinkingLevelMap
+                : thinkingLevels(entry.reasoning_options.effort, sibling),
+        type: 'chat',
+    };
+}
+/**
+ * Union the snapshot roster onto one catalog provider. Installed models win
+ * on conflict and classifier-roster ids stay on pi-ai's classifier path, so
+ * the merged list always covers the installed catalog — a stale snapshot
+ * delays additions but never removes a working model.
+ * @param catalog - the installed pi-ai catalog provider for one route.
+ * @param route - the route the snapshot section is keyed under.
+ * @returns the catalog provider, or a shallow clone serving the union.
+ */
+export function withFreshModels(catalog, route) {
+    const section = SNAPSHOT[route];
+    const installed = new Map(catalog.getModels().map(model => [model.id, model]));
+    const classifiers = new Set(SNAPSHOT.classifiers);
+    const catalogModels = catalog.getModels();
+    const extras = [];
+    for (const id of section.roster) {
+        if (installed.has(id) || classifiers.has(id))
+            continue;
+        const marker = section.fallback.includes(id);
+        const key = marker ? undefined : section.entries[id];
+        if (!marker && key === undefined) {
+            throw new Error(`dsh-auth: snapshot ${route}/${id} is on the roster but has neither metadata nor a fallback marker`);
+        }
+        extras.push(synthesize(catalogModels, route, id, key));
+    }
+    if (extras.length === 0)
+        return catalog;
+    return {
+        ...catalog,
+        getModels: () => [...catalog.getModels(), ...extras],
+    };
+}
+/** Snapshot roster ids for one route, for smoke coverage. */
+export function freshRosterIds(route) {
+    return SNAPSHOT[route].roster.slice();
+}

package/node_modules/@askdkc/dsh-auth/lib/index.d.ts

@@ -73,6 +73,7 @@ export type { AskFn, QuestionBridgeHelpers } from './interaction.js';
 export { copyToClipboard, openInBrowser, openerFor } from './opener.js';
 export { CredentialFile, defaultCredentialsFile } from './credentials.js';
 export { OAUTH_PROVIDER_IDS, CATALOG_PROVIDER_IDS, AUTH_PROVIDER_IDS, canonicalProvider, buildOAuthProfile, type ModelOverride } from './profiles.js';
+export { freshRosterIds, type FreshRouteId } from './fresh-models.js';
 /**
  * The adapter the plugin registers: a {@link PiAiAdapter} whose *advisory
  * catalog* is credential-gated. A provider with no stored credential

package/node_modules/@askdkc/dsh-auth/lib/index.js

@@ -68,6 +68,7 @@ export { QuestionBridge, describeEvent } from './interaction.js';
 export { copyToClipboard, openInBrowser, openerFor } from './opener.js';
 export { CredentialFile, defaultCredentialsFile } from './credentials.js';
 export { OAUTH_PROVIDER_IDS, CATALOG_PROVIDER_IDS, AUTH_PROVIDER_IDS, canonicalProvider, buildOAuthProfile } from './profiles.js';
+export { freshRosterIds } from './fresh-models.js';
 /**
  * The ambient auth context providers may consult while resolving their own
  * auth. `env()` answers from the process environment; `fileExists()` answers