amicus 3.1.0 → 3.2.0

package/src/utils/model-tiers.js

@@ -0,0 +1,120 @@
+/**
+ * Per-vendor cost tiers (economy/balanced/frontier) + resolution against the
+ * live model catalog.
+ *
+ * Tier ordering: frontier = MOST expensive/capable, economy = CHEAPEST,
+ * balanced = the middle ground.
+ *
+ * Mirrors quick-picks.pickCurrent's "newest live-catalog id matching a
+ * pattern in a vendor namespace" approach rather than reinventing it: each
+ * tier's regex is matched over the model segment in BOTH the direct
+ * namespace (`<vendor>/<model>`) and the OpenRouter namespace
+ * (`openrouter/<vendor>/<model>`); the direct-namespace pick wins when both
+ * exist, since storage is direct-first (see gateway-router.js).
+ *
+ * Gateway-only vendors (no direct API integration — provider-registry
+ * `isDirectProvider` false) have no tier regexes here: OpenRouter is their
+ * only route, and curated-models' CARDLESS/family-fallback entries don't
+ * carry a per-alias match pattern the way FAMILIES does, so there is no
+ * live-catalog rule to reuse for them. All three tiers resolve to the same
+ * curated flagship — the static canonical pin `toDefaultAliases()` already
+ * maintains for that vendor's alias (the same pin `resolveQuickPicks` falls
+ * back to when live resolution is unavailable).
+ */
+
+'use strict';
+
+const { pickCurrent } = require('./quick-picks');
+const { isDirectProvider } = require('./provider-registry');
+const { toDefaultAliases, listCuratedRoutes } = require('./curated-models');
+
+/** Tier regex table: pattern matches the model segment after `<vendor>/` (or `openrouter/<vendor>/`). */
+const TIERS = {
+  anthropic: {
+    economy: /^claude-haiku-/,
+    balanced: /^claude-sonnet-/,
+    frontier: /^claude-opus-/,
+  },
+  openai: {
+    economy: /^gpt-[\d.]+-mini$/,
+    balanced: /^gpt-[\d.]+$/,
+    frontier: /^gpt-[\d.]+-pro$/,
+  },
+  google: {
+    economy: /^gemini-[\d.]+-flash-lite/,
+    balanced: /^gemini-[\d.]+-flash(?!-lite)/,
+    frontier: /^gemini-[\d.]+-pro/,
+  },
+  deepseek: {
+    economy: /^deepseek-v[\d.]+$/,
+    balanced: /^deepseek-v[\d.]+$/,
+    frontier: /^deepseek-v[\d.]+-pro$/,
+  },
+};
+
+/** Fallback preference order when the requested tier's pattern matches nothing. */
+const TIER_ORDER = ['economy', 'balanced', 'frontier'];
+
+/**
+ * vendor -> curated alias, for vendors with no direct integration and no
+ * TIERS entry. Built once from curated-models' OpenRouter-routed entries;
+ * the first alias found per vendor wins (e.g. 'qwen' over its
+ * 'qwen-coder'/'qwen-flash' siblings, since CARDLESS lists it first).
+ * @returns {Object<string,string>}
+ */
+function buildGatewayOnlyAliasMap() {
+  const map = {};
+  for (const { alias, provider, model } of listCuratedRoutes()) {
+    if (provider !== 'openrouter' || !model.startsWith('openrouter/')) { continue; }
+    const rest = model.slice('openrouter/'.length); // '<vendor>/<rest...>'
+    const slash = rest.indexOf('/');
+    const vendor = slash > 0 ? rest.slice(0, slash) : null;
+    if (!vendor || isDirectProvider(vendor) || TIERS[vendor] || map[vendor]) { continue; }
+    map[vendor] = alias;
+  }
+  return map;
+}
+
+const GATEWAY_ONLY_ALIAS = buildGatewayOnlyAliasMap();
+
+/** Newest catalog id matching `regex` under `vendor`; direct namespace preferred over OpenRouter's. */
+function pickForTier(catalog, vendor, regex) {
+  return pickCurrent(catalog, '', vendor, regex) || pickCurrent(catalog, 'openrouter/', vendor, regex);
+}
+
+/** True when the catalog has ANY row (any tier) under this vendor's namespace, in either gateway. */
+function vendorHasModels(catalog, vendor) {
+  return Boolean(pickForTier(catalog, vendor, /./));
+}
+
+/**
+ * @param {string} vendor
+ * @param {'economy'|'balanced'|'frontier'} tier
+ * @param {Array<{id:string}>} catalog
+ * @returns {string|null} current live-catalog full id for vendor+tier
+ *   (e.g. `anthropic/claude-sonnet-5`), or null when the vendor is unknown
+ *   or absent from the catalog.
+ */
+function resolveTier(vendor, tier, catalog) {
+  if (typeof vendor !== 'string' || !vendor) { return null; }
+  if (!TIER_ORDER.includes(tier)) { return null; }
+
+  const gatewayAlias = GATEWAY_ONLY_ALIAS[vendor];
+  if (gatewayAlias) { return toDefaultAliases()[gatewayAlias] || null; }
+
+  const table = TIERS[vendor];
+  if (!table) { return null; }
+
+  const direct = pickForTier(catalog, vendor, table[tier]);
+  if (direct) { return direct; }
+
+  if (!vendorHasModels(catalog, vendor)) { return null; }
+
+  for (const t of TIER_ORDER) {
+    const pick = pickForTier(catalog, vendor, table[t]);
+    if (pick) { return pick; }
+  }
+  return null;
+}
+
+module.exports = { TIERS, resolveTier };

package/src/utils/provider-default-picker.js

@@ -0,0 +1,234 @@
+/**
+ * Provider-default picker core (Part 2, Task 4).
+ *
+ * Builds the priced, tier-preselected choice list a vendor's model picker
+ * (CLI/Electron/readline, later tasks) renders. This module is PURE and
+ * transport-agnostic: the catalog is always injected by the caller, and it
+ * never imports a renderer's formatting helper (e.g. Electron's `fmtPrice`)
+ * -- `pricePerMInput` is returned as a raw number; each surface formats it.
+ *
+ * The one documented impurity: when `tier` is omitted, `getCostTier()` reads
+ * the user's persisted config (Task 1). Callers that need full purity can
+ * always pass `tier` explicitly to skip that read entirely.
+ */
+
+'use strict';
+
+const { resolveTier } = require('./model-tiers');
+const { getCostTier, loadConfig, saveConfig } = require('./config');
+const { pairAcrossGateways } = require('./gateway-route-catalog');
+const { toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
+
+/**
+ * @param {{pricing?: {prompt?: string|number|null}|null}|null|undefined} orRow
+ *   the OpenRouter-namespace catalog row paired to a logical model, if any.
+ * @returns {number|null} `pricing.prompt * 1e6` ($/M input tokens), or null
+ *   when there is no priced OpenRouter twin.
+ */
+function pricePerMInputFrom(orRow) {
+  if (!orRow || !orRow.pricing || orRow.pricing.prompt === null || orRow.pricing.prompt === undefined) {
+    return null;
+  }
+  const n = Number(orRow.pricing.prompt);
+  return Number.isFinite(n) ? n * 1e6 : null;
+}
+
+/**
+ * Every catalog row belonging to `vendor`, in either namespace (direct
+ * `<vendor>/<model>` or OpenRouter `openrouter/<vendor>/<model>`).
+ * @param {Array<{id:string}>} catalog
+ * @param {string} vendor
+ * @returns {Array<{id:string}>}
+ */
+function vendorRowsIn(catalog, vendor) {
+  const directPrefix = `${vendor}/`;
+  const orPrefix = `openrouter/${vendor}/`;
+  return catalog.filter(r => r && typeof r.id === 'string' &&
+    (r.id.startsWith(directPrefix) || r.id.startsWith(orPrefix)));
+}
+
+/**
+ * Choose the verbatim catalog id a single catalog `row` should surface as in
+ * the picker -- NEVER fabricates an id.
+ *
+ * A direct-namespace row always keeps its own (real, direct-callable) id,
+ * regardless of what `pairAcrossGateways` could resolve for it -- this is
+ * what keeps BOTH direct rows around when two direct ids are ambiguous to
+ * `pairAcrossGateways` (e.g. a bare alias and a dated pinned snapshot that
+ * normalize to the same key): each is still a real, distinct, callable id
+ * and must not be dropped or silently merged.
+ *
+ * An OpenRouter-namespace row is collapsed onto a direct id only when
+ * `pairAcrossGateways` found exactly one (unambiguous) direct twin -- that's
+ * a real catalog id, safe to reuse for dedup. Otherwise: for
+ * `DIVERGENT_VENDORS` (direct ids don't share a string form with
+ * OpenRouter's -- e.g. anthropic's dash-vs-dot versioning), the row keeps
+ * its OpenRouter-prefixed id as-is; stripping the prefix would fabricate a
+ * non-direct-callable dot-form id no row actually carries. Non-divergent
+ * vendors keep the pre-existing strip via `toCanonicalDefault`, which is
+ * safe because their direct and OpenRouter ids are identical once the
+ * `openrouter/<vendor>/` prefix is removed (mirrors curated-models.js's
+ * `directFormFor` policy).
+ * @param {string} vendor
+ * @param {boolean} isDirect whether `row.id` is itself a direct-namespace id
+ * @param {{id:string}} row
+ * @param {{direct?:string, openrouter?:string}} paired
+ * @returns {string|null}
+ */
+function chooseRowId(vendor, isDirect, row, paired) {
+  if (isDirect) { return row.id; }
+  if (paired.direct) { return paired.direct; }
+  if (!paired.openrouter) { return null; }
+  return DIVERGENT_VENDORS.has(vendor) ? paired.openrouter : toCanonicalDefault(paired.openrouter);
+}
+
+/**
+ * Dedupe `vendor`'s catalog rows across gateways into one row per logical
+ * model, reusing `pairAcrossGateways` (never re-deriving the pairing logic).
+ * Every row id is verbatim from the catalog (see `chooseRowId`) -- never
+ * fabricated, and a direct row is never dropped even when its OpenRouter
+ * twin is ambiguous.
+ * @param {Array<{id:string,name:string,contextLength:(number|null)}>} catalog
+ * @param {string} vendor
+ * @returns {Array<{id:string,name:string,contextLength:(number|null),pricePerMInput:(number|null),isPreselected:boolean}>}
+ */
+function buildRows(catalog, vendor) {
+  const byId = new Map(catalog.filter(r => r && typeof r.id === 'string').map(r => [r.id, r]));
+  const catalogInfo = { models: catalog };
+  const directPrefix = `${vendor}/`;
+  const orPrefix = `openrouter/${vendor}/`;
+
+  const rows = [];
+  const seenIds = new Set();
+
+  for (const row of vendorRowsIn(catalog, vendor)) {
+    const isDirect = row.id.startsWith(directPrefix);
+    const token = isDirect ? row.id.slice(directPrefix.length) : row.id.slice(orPrefix.length);
+    const paired = pairAcrossGateways(vendor, token, catalogInfo);
+    const chosenId = chooseRowId(vendor, isDirect, row, paired);
+    if (!chosenId || seenIds.has(chosenId)) { continue; }
+    seenIds.add(chosenId);
+
+    const orRow = paired.openrouter ? byId.get(paired.openrouter) : null;
+    const sourceRow = isDirect ? row : ((paired.direct && byId.get(paired.direct)) || orRow || row);
+
+    rows.push({
+      id: chosenId,
+      name: sourceRow.name,
+      contextLength: (sourceRow.contextLength === undefined ? null : sourceRow.contextLength),
+      pricePerMInput: pricePerMInputFrom(orRow),
+      isPreselected: false,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Canonicalize `resolveTier`'s verbatim catalog-id output the same way row
+ * ids are built (`chooseRowId`), so it can be matched against `rows`
+ * exactly. `resolveTier` already prefers a real direct id when one matches
+ * the tier pattern (`model-tiers.js`'s `pickForTier` tries the direct
+ * namespace first), so this only has an effect when it fell back to an
+ * OpenRouter id (no matching direct-namespace row at all). For
+ * `DIVERGENT_VENDORS`, that OpenRouter id must stay OpenRouter-prefixed --
+ * stripping it would fabricate a non-direct-callable dot-form id that no row
+ * carries. Non-divergent vendors keep the pre-existing strip, safe because
+ * their direct and OpenRouter ids are identical once the prefix is removed.
+ * @param {string} vendor
+ * @param {string|null} resolved verbatim catalog id from `resolveTier`, or null
+ * @returns {string|null}
+ */
+function canonicalizeResolved(vendor, resolved) {
+  if (!resolved) { return null; }
+  return DIVERGENT_VENDORS.has(vendor) ? resolved : toCanonicalDefault(resolved);
+}
+
+/**
+ * Decide which row (by id) should be preselected.
+ * Primary: `resolveTier(vendor, tier, catalog)`, canonicalized the same way
+ * row ids are (direct-first) so it can match a row exactly. Falls back to
+ * the cheapest priced row, then the first row, whenever the primary result
+ * is null OR (defensively) doesn't correspond to any built row.
+ * @param {string} vendor
+ * @param {string|undefined} tier
+ * @param {Array<{id:string}>} catalog
+ * @param {Array<{id:string,pricePerMInput:(number|null)}>} rows non-empty
+ * @returns {string} a row id from `rows`
+ */
+function computePreselectedId(vendor, tier, catalog, rows) {
+  const effectiveTier = tier || getCostTier();
+  const resolved = resolveTier(vendor, effectiveTier, catalog);
+  const canonical = canonicalizeResolved(vendor, resolved);
+  if (canonical && rows.some(r => r.id === canonical)) { return canonical; }
+
+  const priced = rows.filter(r => r.pricePerMInput !== null);
+  if (priced.length > 0) {
+    return priced.reduce((cheapest, r) => (r.pricePerMInput < cheapest.pricePerMInput ? r : cheapest)).id;
+  }
+  return rows[0].id;
+}
+
+/** Preselected first; then price ascending; null prices last. Stable otherwise. */
+function compareRows(a, b) {
+  if (a.isPreselected !== b.isPreselected) { return a.isPreselected ? -1 : 1; }
+  if (a.pricePerMInput === null && b.pricePerMInput === null) { return 0; }
+  if (a.pricePerMInput === null) { return 1; }
+  if (b.pricePerMInput === null) { return -1; }
+  return a.pricePerMInput - b.pricePerMInput;
+}
+
+/**
+ * Build the choice list for a vendor's model picker.
+ * @param {string} vendor e.g. 'anthropic'
+ * @param {{catalog?: Array<{id:string,name:string,contextLength:(number|null),pricing:(object|null)}>, tier?: string}} [options]
+ * @returns {{preselectedId: (string|null), rows: Array<{id:string,name:string,contextLength:(number|null),pricePerMInput:(number|null),isPreselected:boolean}>}}
+ */
+function buildProviderDefaultChoices(vendor, options = {}) {
+  if (typeof vendor !== 'string' || !vendor) { return { preselectedId: null, rows: [] }; }
+
+  const catalog = Array.isArray(options.catalog) ? options.catalog : [];
+  const rows = buildRows(catalog, vendor);
+  if (rows.length === 0) { return { preselectedId: null, rows: [] }; }
+
+  const preselectedId = computePreselectedId(vendor, options.tier, catalog, rows);
+  for (const r of rows) { r.isPreselected = r.id === preselectedId; }
+  rows.sort(compareRows);
+
+  return { preselectedId, rows };
+}
+
+/**
+ * Apply a picker choice: store the vendor-named alias and (optionally) seed
+ * `config.default` on first use. Read-modify-write, NO-CLOBBER -- preserves
+ * an already-set `config.default` and every other existing alias/key.
+ *
+ * `chosenId` is a verbatim catalog id straight from `buildProviderDefaultChoices`
+ * (via `chooseRowId`/`computePreselectedId`): a real direct id, or -- for a
+ * `DIVERGENT_VENDORS` vendor with no direct twin -- an `openrouter/`-prefixed
+ * id. **Never** run `toCanonicalDefault` on a divergent vendor's id: that
+ * would strip the `openrouter/` prefix and fabricate a non-direct-callable
+ * dot-form id no row actually carries (the exact bug just fixed in Task 4's
+ * `chooseRowId`/`canonicalizeResolved`). Non-divergent vendors' direct and
+ * OpenRouter ids are identical once the prefix is stripped, so
+ * `toCanonicalDefault` is safe there.
+ * @param {string} vendor e.g. 'anthropic'
+ * @param {string} chosenId verbatim catalog id from the picker
+ * @param {{seedDefaultIfAbsent?: boolean}} [options]
+ * @returns {{alias: string, setAsDefault: boolean}}
+ */
+function applyProviderDefault(vendor, chosenId, { seedDefaultIfAbsent = true } = {}) {
+  const storedId = DIVERGENT_VENDORS.has(vendor) ? chosenId : toCanonicalDefault(chosenId);
+
+  const config = loadConfig() || {};
+  if (!config.aliases || typeof config.aliases !== 'object') { config.aliases = {}; }
+  config.aliases[vendor] = storedId;
+
+  const hasDefault = typeof config.default === 'string' && config.default.trim().length > 0;
+  const setAsDefault = seedDefaultIfAbsent && !hasDefault;
+  if (setAsDefault) { config.default = vendor; }
+
+  saveConfig(config);
+  return { alias: vendor, setAsDefault };
+}
+
+module.exports = { buildProviderDefaultChoices, applyProviderDefault };

package/src/utils/provider-default-prompt.js

@@ -0,0 +1,118 @@
+/**
+ * Provider-default prompt flow (Part 2, Task 6/7 shared helper).
+ *
+ * Wraps the transport-agnostic picker core (`provider-default-picker.js`) in
+ * a single reusable flow that both the CLI (`amicus key`, Task 6) and the
+ * readline setup wizard (Task 7) call after a provider's API key is saved:
+ * build the priced choice list, either prompt for a selection (interactive)
+ * or silently take the tier-preselected id (non-interactive), then apply it.
+ *
+ * Transport-agnostic by injection: `ask` (a `(prompt: string) => Promise<string>`
+ * readline reader) and `print` (a `(line: string) => void` line writer) are
+ * both passed in by the caller, so this module is unit-testable without a
+ * real TTY and never imports `readline`/`console` itself.
+ */
+
+'use strict';
+
+const { buildProviderDefaultChoices, applyProviderDefault } = require('./provider-default-picker');
+const { isDirectProvider } = require('./provider-registry');
+
+/** Format a $/M-input price for display; `null`/`undefined` -> 'n/a'. @param {number|null|undefined} pricePerMInput */
+function formatPrice(pricePerMInput) {
+  return (pricePerMInput === null || pricePerMInput === undefined)
+    ? 'n/a'
+    : `$${pricePerMInput.toFixed(2)}/M in`;
+}
+
+/** One numbered display line for a single choice row. @param {object} row @param {number} index 1-based */
+function formatRow(row, index) {
+  const ctx = (row.contextLength === null || row.contextLength === undefined) ? '' : ` · ctx ${row.contextLength}`;
+  const recommended = row.isPreselected ? '  (recommended)' : '';
+  return `  ${index}) ${row.name}${ctx} · ${formatPrice(row.pricePerMInput)}${recommended}`;
+}
+
+/**
+ * Read one selection line, re-prompting once on an invalid non-empty entry
+ * before falling back to the preselected id. Empty input (bare Enter) always
+ * accepts the preselected id immediately, no re-prompt.
+ * @param {(prompt: string) => Promise<string>} ask
+ * @param {(line: string) => void} print
+ * @param {{preselectedId: string, rows: Array<{id: string}>}} choices
+ * @returns {Promise<string>}
+ */
+async function promptForChoice(ask, print, choices) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const answer = (await ask(`Pick a number (1-${choices.rows.length}, Enter for recommended): `) || '').trim();
+    if (answer === '') { return choices.preselectedId; }
+    if (/^\d+$/.test(answer)) {
+      const num = Number.parseInt(answer, 10);
+      if (num >= 1 && num <= choices.rows.length) {
+        return choices.rows[num - 1].id;
+      }
+    }
+    if (attempt === 0) { print(`Invalid choice: "${answer}".`); }
+  }
+  return choices.preselectedId;
+}
+
+/**
+ * Run the per-provider default-model flow: build choices, resolve a pick
+ * (prompted or silent), apply it, and hand back a one-line summary for the
+ * caller to print. Never throws for an empty/offline catalog -- callers
+ * should still wrap this in a try/catch (a picker bug must never abort an
+ * already-successful key save).
+ *
+ * Gateway providers (e.g. `openrouter`) are a graceful no-op: `openrouter` is
+ * the GATEWAY, not a model vendor, so `buildProviderDefaultChoices` would
+ * match every OR-namespaced catalog row, "recommended" would be arbitrary,
+ * and writing `aliases.openrouter = "<some vendor>/<model>"` would be
+ * nonsensical. Per-provider defaults only make sense for DIRECT model
+ * vendors (`provider-registry.isDirectProvider`) -- no choices are built, no
+ * alias is written, and `config.default` is never seeded for a gateway.
+ * @param {string} provider vendor name, e.g. 'anthropic'
+ * @param {{interactive?: boolean, ask?: (prompt: string) => Promise<string>,
+ *   catalog?: Array<object>, print?: (line: string) => void}} [options]
+ * @returns {Promise<{chosenId: (string|null), setAsDefault: boolean, summaryLine: string}>}
+ */
+async function runProviderDefaultFlow(provider, options = {}) {
+  const { interactive = false, ask } = options;
+  const catalog = Array.isArray(options.catalog) ? options.catalog : [];
+  const print = typeof options.print === 'function' ? options.print : () => {};
+
+  if (!isDirectProvider(provider)) {
+    return {
+      chosenId: null,
+      setAsDefault: false,
+      summaryLine: 'Per-provider defaults apply to direct provider keys (openai/anthropic/google/deepseek) -- ' +
+        'models routed via OpenRouter use your overall default.',
+    };
+  }
+
+  const choices = buildProviderDefaultChoices(provider, { catalog });
+  if (!choices.rows || choices.rows.length === 0) {
+    return {
+      chosenId: null,
+      setAsDefault: false,
+      summaryLine: `Couldn't reach the model catalog for ${provider} — no default set. ` +
+        `Run \`amicus key ${provider}\` again later.`,
+    };
+  }
+
+  let chosenId = choices.preselectedId;
+  if (interactive && typeof ask === 'function') {
+    print('');
+    print(`Pick a default model for ${provider}:`);
+    choices.rows.forEach((row, i) => print(formatRow(row, i + 1)));
+    print('');
+    chosenId = await promptForChoice(ask, print, choices);
+  }
+
+  const { setAsDefault } = applyProviderDefault(provider, chosenId, { seedDefaultIfAbsent: true });
+  const summaryLine = `\`amicus start --model ${provider}\` → ${chosenId}` +
+    (setAsDefault ? ', set as your default model' : '');
+
+  return { chosenId, setAsDefault, summaryLine };
+}
+
+module.exports = { runProviderDefaultFlow, formatPrice, formatRow };

package/src/utils/result-schema.js

@@ -182,15 +182,22 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
 
 /**
  * Build an alias-audit document (`models --check --json`).
- * @param {{stale: Array<{alias,model,source,suggestions}>, catalogAvailable: boolean}} opts
+ * `gatewayFindings` (Task 6, #gwid) is additive: the per-gateway-form audit
+ * of curated DEFAULT aliases (toGatewayRoutes() vs. the live catalog),
+ * distinct from the flat `stale` audit above. Defaults to [] so existing
+ * callers that omit it are unaffected.
+ * @param {{stale: Array<{alias,model,source,suggestions}>, catalogAvailable: boolean,
+ *   gatewayFindings?: Array<{alias,gateway,kind,model,expected?}>}} opts
  */
-function buildAuditDoc({ stale, catalogAvailable }) {
+function buildAuditDoc({ stale, catalogAvailable, gatewayFindings = [] }) {
   return {
     schemaVersion: SCHEMA_VERSION,
     type: 'alias-audit',
     catalogAvailable,
     staleCount: stale.length,
     stale,
+    gatewayFindingsCount: gatewayFindings.length,
+    gatewayFindings,
   };
 }
 

package/src/utils/route-error.js

@@ -6,8 +6,9 @@
  *   - `toCliMessage`      -> a human stderr string for the CLI
  *
  * Pure module: no I/O, no requires of launch modules (cli.js/headless.js/
- * mcp-server.js/etc). Additive only — not imported by any launch path yet;
- * wiring is a later task in the #61 Integration plan.
+ * mcp-server.js/etc). Wired into live launch paths — start-helpers.js,
+ * sidecar/fanout-leg.js, and mcp-server.js all render RouteResults through
+ * toStructuredError/toCliMessage.
  *
  * Router error shape (src/utils/model-descriptor.js `routeError()`):
  *   {kind:'error', type:'model_route_error', field, requested, reason,
@@ -15,16 +16,28 @@
  * Selection shape (`selectionRequired()`):
  *   {kind:'selection_required', requested, suggestions}
  *
- * The router's error `reason` is a closed set of 7 values (ROUTE_ERROR_REASONS
- * below). A `selection_required` result has no `reason` of its own — it is
- * synthesized here as SELECTION_REQUIRED_REASON, kept in the same documented
- * REASON_TEXT map rather than invented ad hoc, so callers can treat every
- * rendered structured error the same way regardless of which RouteResult
- * produced it.
+ * The router's error `reason` is NOT limited to the 7 values in
+ * ROUTE_ERROR_REASONS below — that array is just the original/base set,
+ * intentionally pinned as-is (see its own doc comment). The router can also
+ * emit availability reasons (`direct_unavailable`, `openrouter_unavailable`),
+ * which have REASON_TEXT/FIX_HINTS entries but are deliberately excluded from
+ * ROUTE_ERROR_REASONS. A `selection_required` result has no `reason` of its
+ * own — it is synthesized here as SELECTION_REQUIRED_REASON, kept in the same
+ * documented REASON_TEXT map rather than invented ad hoc, so callers can
+ * treat every rendered structured error the same way regardless of which
+ * RouteResult produced it.
  */
 'use strict';
 
-/** The closed set of reasons a router `error` result can carry. */
+/**
+ * The original/base set of router error reasons — NOT an exhaustive list of
+ * every reason a router error can carry. Pinned to exactly these 7 values by
+ * a back-compat test (route-error.test.js:14-24), so this array must not be
+ * extended when new reasons are added. The router also emits
+ * `direct_unavailable` and `openrouter_unavailable` (REASON_TEXT/FIX_HINTS
+ * below have entries for both); those are intentionally left out of this
+ * array. Do not use ROUTE_ERROR_REASONS as an exhaustive switch/allow-list.
+ */
 const ROUTE_ERROR_REASONS = Object.freeze([
   'gateway_conflict',
   'no_openrouter_key',
@@ -51,6 +64,8 @@ const REASON_TEXT = Object.freeze({
   no_key_for_vendor: 'No API key was found for this vendor via any gateway.',
   model_not_found: 'The requested model was not found in the catalog.',
   invalid_descriptor: 'The model identifier could not be parsed.',
+  direct_unavailable: "This model isn't available on the vendor's direct API; use OpenRouter or a different model.",
+  openrouter_unavailable: "This model isn't on OpenRouter; use --gateway direct or a different model.",
   [SELECTION_REQUIRED_REASON]: 'Multiple models match your request; a specific one must be selected.',
 });
 
@@ -63,6 +78,8 @@ const FIX_HINTS = Object.freeze({
   no_key_for_vendor: 'Add a provider key or an OpenRouter key.',
   model_not_found: 'Run `amicus models --refresh`, or pass --no-validate-model.',
   invalid_descriptor: 'Use a vendor/model id or a configured alias.',
+  direct_unavailable: 'Drop --gateway direct (use auto or --gateway openrouter), or pick a different model.',
+  openrouter_unavailable: 'Use --gateway direct, or pick a different model.',
   [SELECTION_REQUIRED_REASON]: 'Pick one of the suggestions below, or narrow the model id.',
 });