amicus 4.8.0 → 4.8.1

package/src/utils/alias-audit.js

@@ -1,10 +1,21 @@
 /**
- * Alias Audit (F5) — report + suggest, never auto-repair.
+ * Alias Audit (F5) — report + suggest for most classes; doctor --fix auto-repairs one narrow, mechanically-unambiguous class (B3).
  *
  * Finds aliases/routes pointing at models absent from the catalog and
  * suggests current same-vendor replacements. Pure functions over inputs;
  * collectAliasSources() does the gathering. Consumed by `amicus models
  * --check` and the npm wrapper scripts.
+ *
+ * `findFabricatedAliasRepairs()` (B3, council review of PR 198) is the one
+ * exception to "never auto-repair": it detects the single class `doctor
+ * --fix` can safely rewrite unattended -- a bare id `classifyModel` proves
+ * `invalid` on the `direct` gateway AND for which the catalog holds an
+ * unambiguous OpenRouter twin (`pairAcrossGateways`, never string
+ * concatenation) -- still pure detection here; the actual write lives in
+ * `doctor-alias-check.js`'s `repairAlias()`. Every OTHER class this module
+ * finds (typo, retired model, ambiguous twin, drifted-but-live) stays
+ * report-and-suggest only, same as before -- this module does not become a
+ * general auto-repair tool.
  */
 
 'use strict';
@@ -132,7 +143,10 @@ function suggestReplacements(staleModel, catalog, n = 3) {
  * fresh `amicus setup` would seed today — the v4.6.1 release-gate class
  * (stored `gemini` -> 3.1-flash-lite-preview: still catalog-listed so
  * findStaleAliases passes it, no longer what the family resolves to).
- * Report + suggest, never auto-repair (this module's charter).
+ * Report + suggest only -- unlike `findFabricatedAliasRepairs` below (B3's
+ * narrow, mechanically-unambiguous exception), THIS function never
+ * auto-repairs: a drifted-but-live target has no single unambiguous
+ * "correct" answer to converge on the way a fabricated id does.
  *
  * Only user-config rows are checked (defaults/curated follow the catalog by
  * construction), only for aliases that are quick-pick families (a custom
@@ -178,4 +192,68 @@ function findDriftedStoredAliases(sources, catalog) {
     .map(({ alias, model }) => ({ alias, stored: model, current: current.get(alias).display }));
 }
 
-module.exports = { collectAliasSources, findStaleAliases, findDriftedStoredAliases, suggestReplacements };
+/**
+ * B3 (council review of PR 198, issue 195): the narrow, mechanically-
+ * unambiguous class of stored alias `doctor --fix` may repair -- a bare
+ * `<vendor>/<model>` id in a 'user-config' row (what's actually persisted to
+ * `config.aliases`, the only source a repair can rewrite) that
+ * `classifyModel` proves `invalid` on the `direct` gateway AND for which the
+ * catalog contains an unambiguous OpenRouter twin (`pairAcrossGateways` --
+ * never string-concatenation). This is exactly the class the pre-fix
+ * v4.8.0 `chooseRowId`/`applyProviderDefault` could persist (an unconditional
+ * `openrouter/` strip with no catalog evidence); PR 198's
+ * `directFormIfProven` (model-canonicalization.js) now refuses to write it
+ * going forward, so this function finds the ones already ON DISK and
+ * converges them onto the same OpenRouter-prefixed answer the picker would
+ * offer today, rather than inventing a third one.
+ *
+ * Deliberately narrower than findStaleAliases: a typo'd, retired, or
+ * user-invented id also classifies `invalid`, but `pairAcrossGateways` can
+ * only find a twin when the extracted vendor + version token names a REAL
+ * model that still exists, under that exact normalized name, in the
+ * catalog's OpenRouter namespace -- a typo or a genuinely dead model can
+ * never satisfy that. Ambiguous (>1 match) or absent twins are left
+ * untouched -- still reported as stale by findStaleAliases, never repaired.
+ *
+ * DIVERGENT_VENDORS (e.g. anthropic) are excluded on purpose:
+ * model-canonicalization.js gates that set FIRST and unconditionally, so its
+ * predicates never strip a divergent vendor's prefix in the first place --
+ * a bare divergent-vendor alias could not have been produced by the bug
+ * this repairs, so treating one as fabricated here would be inventing a new
+ * class, not converging on the picker's own answer.
+ *
+ * Empty/absent catalog -> [] : classifyModel can only return 'unknown' with
+ * no catalog rows, and 'unknown' never authorises a repair -- no positive
+ * evidence, no write.
+ * @param {Array<{alias:string,model:string,source:string}>} sources
+ * @param {Array<{id:string}>} catalog
+ * @returns {Array<{alias:string,oldId:string,newId:string}>}
+ */
+function findFabricatedAliasRepairs(sources, catalog) {
+  if (!catalog || catalog.length === 0) { return []; }
+  const { classifyModel } = require('./model-classification');
+  const { pairAcrossGateways } = require('./gateway-route-catalog');
+  const { DIVERGENT_VENDORS } = require('./curated-models');
+  const catalogInfo = { models: catalog };
+
+  const out = [];
+  for (const { alias, model, source } of sources) {
+    if (source !== 'user-config') { continue; }
+    if (typeof model !== 'string' || model.startsWith('openrouter/')) { continue; } // not bare
+    const parts = model.split('/');
+    if (parts.length < 2) { continue; } // not a <vendor>/<model> shape
+    const vendor = parts[0];
+    if (DIVERGENT_VENDORS.has(vendor)) { continue; }
+    const versionToken = parts.slice(1).join('/');
+    if (classifyModel(model, 'direct', catalogInfo) !== 'invalid') { continue; }
+    const paired = pairAcrossGateways(vendor, versionToken, catalogInfo);
+    if (!paired.openrouter) { continue; } // ambiguous or absent twin -- leave as a warning
+    out.push({ alias, oldId: model, newId: paired.openrouter });
+  }
+  return out;
+}
+
+module.exports = {
+  collectAliasSources, findStaleAliases, findDriftedStoredAliases, suggestReplacements,
+  findFabricatedAliasRepairs,
+};

package/src/utils/curated-models.js

@@ -112,11 +112,11 @@ const CARDLESS = [
   { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.6' } },
   { alias: 'seed', routes: { openrouter: 'openrouter/bytedance-seed/seed-2.0-lite' } },
   // inkling added 2026-08-14: the council-review workflow's default bench
-  // names it, and a workflow can only use aliases this table ships — a CI
-  // runner has no user config, so a locally-defined alias resolves to
-  // nothing there. Pinned to the full model, not `inkling-small`: the bench
-  // seat wants the flagship's judgment. `:batch` is deliberately not pinned
-  // (deferred completion is wrong for an interactive council leg).
+  // names it, and this table is the FLOOR a runner falls back to when no
+  // alias map is provisioned (workflow_call callers, forks) — there, a
+  // locally defined alias still resolves to nothing. Pinned to the full
+  // model, not `inkling-small`: the bench seat wants the flagship's
+  // judgment. `:batch` is not pinned (wrong for an interactive council leg).
   { alias: 'inkling', routes: { openrouter: 'openrouter/thinkingmachines/inkling' } },
 ];
 

package/src/utils/doctor-alias-check.js

@@ -0,0 +1,152 @@
+// src/utils/doctor-alias-check.js
+'use strict';
+
+/**
+ * @module utils/doctor-alias-check
+ * The `aliases` doctor check ("Model aliases"), split out of
+ * src/cli-handlers-doctor.js to keep that file under the 300-line gate
+ * (mirrors doctor-engine-check.js / doctor-electron-mcp-check.js /
+ * doctor-base-url-check.js / doctor-local-providers-check.js -- same reason,
+ * a different check).
+ *
+ * B3 (council review of PR 198, issue 195): `doctor --fix` repairs exactly
+ * one narrow class of stored alias -- see alias-audit.js's
+ * `findFabricatedAliasRepairs` for the detection rule (classifies `invalid`
+ * on the `direct` gateway AND has an unambiguous OpenRouter twin) and why it
+ * cannot false-positive a typo, a retired model, or a user-invented id.
+ * Repair = rewrite `config.aliases[alias]` to that catalog-confirmed
+ * OpenRouter id -- read-modify-write, no-clobber (mirrors
+ * `applyProviderDefault`, provider-default-picker.js). Every OTHER
+ * stale/drifted alias is left untouched and stays a warning, hinting at
+ * `amicus models --check` same as before this PR.
+ *
+ * A3 (council review of PR 198): the repair ACTION additionally requires the
+ * cached catalog to be FRESH (same `MAX_CATALOG_AGE_MS` window as doctor's
+ * own `catalog` check, cli-handlers-doctor.js). `readCache()` here reads the
+ * exact same cache doctor's `catalog` check may independently report as
+ * `stale (Nh old)` -- without this gate, `--fix` would rewrite a user's
+ * config from data the SAME run just called untrustworthy. A stale catalog
+ * can be missing rows that would make a "fabricated" id look repairable when
+ * it is merely unfetched, so a stale catalog declines the repair (explaining
+ * why via `repairFabricatedAliasStaleCatalog`) rather than writing on
+ * unverified evidence; detection/reporting is unaffected either way.
+ */
+
+const HINTS = require('./remediation-hints');
+
+// Mirrors cli-handlers-doctor.js's own MAX_CATALOG_AGE_MS (which itself
+// mirrors model-catalog.js's DEFAULT_MAX_AGE_MS) -- duplicated rather than
+// imported to avoid a require cycle (cli-handlers-doctor.js requires this
+// module at load time, before its own module.exports exists).
+const MAX_CATALOG_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+
+/**
+ * @param {{fetchedAt?: number}|null} cache
+ * @returns {boolean} true when `cache` exists, has a numeric `fetchedAt`, and
+ *   is no older than `MAX_CATALOG_AGE_MS` -- the same test doctor's `catalog`
+ *   check applies to decide `ok` vs `stale (Nh old)`.
+ */
+function isCatalogFresh(cache) {
+  if (!cache || typeof cache.fetchedAt !== 'number') { return false; }
+  return (Date.now() - cache.fetchedAt) <= MAX_CATALOG_AGE_MS;
+}
+
+/**
+ * Rewrite one alias's stored value in place. Read-modify-write / no-clobber
+ * -- preserves `config.default` and every other alias/key (same contract as
+ * `applyProviderDefault`, provider-default-picker.js).
+ * @param {string} alias
+ * @param {string} newId verbatim catalog id (an OpenRouter-namespace id from
+ *   `pairAcrossGateways` -- never hand-derived by string concatenation)
+ */
+function repairAlias(alias, newId) {
+  const { loadConfig, saveConfig } = require('./config');
+  const config = loadConfig() || {};
+  if (!config.aliases || typeof config.aliases !== 'object') { config.aliases = {}; }
+  config.aliases[alias] = newId;
+  saveConfig(config);
+}
+
+/** One pass: sources + both existing audits + the repairable set, over the same catalog. */
+function computeState(d, catalog) {
+  const sources = d.collectAliasSources();
+  return {
+    sources,
+    stale: d.findStaleAliases(sources, catalog),
+    drifted: d.findDriftedStoredAliases(sources, catalog),
+    repairable: d.findFabricatedAliasRepairs(sources, catalog),
+  };
+}
+
+/**
+ * @param {{readCache: () => ({models?: Array}|null), collectAliasSources: () => Array,
+ *   findStaleAliases: (s:Array, c:Array) => Array, findDriftedStoredAliases: (s:Array, c:Array) => Array,
+ *   findFabricatedAliasRepairs: (s:Array, c:Array) => Array<{alias:string,oldId:string,newId:string}>,
+ *   fix?: boolean, repairAlias?: (alias:string, newId:string) => void}} d
+ * @returns {{id,name,status,message,hint,fixed?,fixDetail?}}
+ */
+function evaluateAliasesCheck(d) {
+  const id = 'aliases';
+  const name = 'Model aliases';
+  const cache = d.readCache();
+  const catalog = (cache && cache.models) || [];
+  const catalogFresh = isCatalogFresh(cache);
+
+  let state = computeState(d, catalog);
+  let fixFields = {};
+
+  // Only under --fix, only when there is something in the narrow,
+  // mechanically-unambiguous class to repair (rule 1), and only on a FRESH
+  // catalog (A3) -- a failed individual rewrite is best-effort -- it simply
+  // stays a warning, same as one findStaleAliases could never resolve.
+  if (d.fix && state.repairable.length > 0 && catalogFresh) {
+    const repaired = [];
+    for (const r of state.repairable) {
+      try { d.repairAlias(r.alias, r.newId); repaired.push(r); }
+      catch { /* best-effort -- an unrepaired alias just stays a warning below */ }
+    }
+    if (repaired.length > 0) {
+      // Rule 6: announce every repair, naming the alias and both ids -- this
+      // fixDetail flows into the 'heal' degrade's `why` field (doctor-degrade.js).
+      const detail = repaired.map((r) => `'${r.alias}' (${r.oldId} -> ${r.newId})`).join('; ');
+      fixFields = {
+        fixed: true,
+        fixDetail: `rewrote ${repaired.length} fabricated alias(es) to its catalog-confirmed OpenRouter id: ${detail}`,
+      };
+      // Rule 5 (idempotency): recompute from a fresh config read so both this
+      // run's message and a second --fix run see the post-repair reality, not
+      // the pre-repair snapshot -- a repaired alias must not still count as
+      // stale/repairable below.
+      state = computeState(d, catalog);
+    }
+  }
+
+  const { stale, drifted, repairable } = state;
+  if (stale.length === 0 && drifted.length === 0) {
+    return {
+      id, name, status: 'ok',
+      message: catalog.length ? 'all resolve' : 'catalog empty — not checked', hint: null,
+      ...fixFields,
+    };
+  }
+  const parts = [];
+  if (stale.length) { parts.push(`${stale.length} stale: ${stale.map((s) => s.alias).join(', ')}`); }
+  if (drifted.length) { parts.push(`${drifted.length} drifted: ${drifted.map((s) => s.alias).join(', ')}`); }
+  // Rule 1: without --fix, report the repairable count and the hint, change
+  // nothing. A3: when the catalog is stale, say so explicitly rather than
+  // offering a fix that will silently decline to write.
+  if (repairable.length) {
+    parts.push(catalogFresh
+      ? `${repairable.length} fixable via doctor --fix`
+      : `${repairable.length} fixable via doctor --fix once the catalog is refreshed (catalog is stale)`);
+  }
+  return {
+    id, name, status: 'warn', message: parts.join('; '),
+    hint: repairable.length === 0
+      ? 'amicus models --check'
+      : (catalogFresh ? HINTS.repairFabricatedAlias : HINTS.repairFabricatedAliasStaleCatalog),
+    ...fixFields,
+  };
+}
+
+module.exports = { evaluateAliasesCheck, repairAlias };

package/src/utils/model-canonicalization.js

@@ -0,0 +1,64 @@
+/**
+ * Direct-first id canonicalization, guarded by `classifyModel`
+ * (model-classification.js). Extracted out of `provider-default-picker.js`
+ * (issue 195 follow-up, F1/B4 -- council review of PR 198) purely to keep
+ * that file under the 300-line size gate; the two function bodies below are
+ * an unmodified move, not a rewrite.
+ *
+ * Two call sites, same predicate (`classifyModel`), opposite defaults --
+ * named separately on purpose so neither behavior can be reached by
+ * accident (e.g. forgetting to pass an option):
+ *
+ * - `directFormIfSafe` -- LIST-BUILDING (`chooseRowId`/`canonicalizeResolved`
+ *   in provider-default-picker.js, building the picker's row list). With no
+ *   catalog evidence either way, a bare policy-routed id is a reasonable
+ *   GUESS to offer: optimistic, strips the `openrouter/` prefix unless
+ *   `classifyModel` can prove the bare form `invalid`.
+ * - `directFormIfProven` -- PERSISTENCE (`applyProviderDefault`, writing
+ *   `config.aliases[vendor]`). By the time an id is persisted, the caller
+ *   has already handed in whatever prefix it decided on -- that prefix IS
+ *   the user's choice, carrying information an empty or absent catalog does
+ *   not contradict. Strips only on POSITIVE evidence (`classifyModel`
+ *   returns `valid`, i.e. the bare id is an actual catalog row); anything
+ *   else -- `unknown` (including a failed/absent catalog fetch, which is
+ *   exactly the case that used to silently re-fabricate the id issue 195
+ *   fixed) or `invalid` -- preserves the id exactly as given.
+ *
+ * Both gate `DIVERGENT_VENDORS` FIRST and internally, always returning the
+ * input unchanged for one of those vendors (dot vs. dash direct ids, e.g.
+ * anthropic) -- a caller cannot reach the optimistic OR the proven strip for
+ * a divergent vendor by forgetting to check the set itself.
+ */
+
+'use strict';
+
+const { toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
+const { classifyModel } = require('./model-classification');
+
+/**
+ * @param {string} vendor
+ * @param {string} orId an `openrouter/<vendor>/<rest>` id (or already-bare)
+ * @param {{models: Array<{id:string, authoritative?: boolean}>}} catalogInfo
+ * @returns {string} the bare direct id when not proven invalid, else `orId` unchanged
+ */
+function directFormIfSafe(vendor, orId, catalogInfo) {
+  if (DIVERGENT_VENDORS.has(vendor)) { return orId; }
+  const bare = toCanonicalDefault(orId);
+  if (bare === orId) { return orId; } // gateway-only vendor -- no direct integration at all
+  return classifyModel(bare, 'direct', catalogInfo) === 'invalid' ? orId : bare;
+}
+
+/**
+ * @param {string} vendor
+ * @param {string} orId an `openrouter/<vendor>/<rest>` id (or already-bare)
+ * @param {{models: Array<{id:string, authoritative?: boolean}>}} catalogInfo
+ * @returns {string} the bare direct id only when PROVEN valid, else `orId` unchanged
+ */
+function directFormIfProven(vendor, orId, catalogInfo) {
+  if (DIVERGENT_VENDORS.has(vendor)) { return orId; }
+  const bare = toCanonicalDefault(orId);
+  if (bare === orId) { return orId; }
+  return classifyModel(bare, 'direct', catalogInfo) === 'valid' ? bare : orId;
+}
+
+module.exports = { directFormIfSafe, directFormIfProven };

package/src/utils/model-shortlist.js

@@ -0,0 +1,100 @@
+/**
+ * Vendor model shortlist (#138) -- the family -> model second level.
+ *
+ * Turns a vendor's deduped, priced picker rows into a
+ * `{suggested, rest}` split so a surface can show a short list without
+ * hiding anything: the GUI renders both groups in one <select>, readline
+ * prints `suggested` and offers `a` to print `rest` too.
+ *
+ * PURE and transport-agnostic, exactly like `provider-default-picker.js`:
+ * the catalog is always injected, and nothing here formats for a renderer.
+ *
+ * Why the caller supplies `recommendedId`: the picker's own preselect is
+ * COST-TIER driven (`computePreselectedId`), which disagrees with the
+ * wizard card's family flagship -- for DeepSeek, `v3.2` vs `v4-pro`.
+ * Owner ruling (#138, 2026-08-24) is that the flagship wins, so that
+ * opening the drill-down and accepting is a guaranteed no-op. The tier
+ * preselect remains the fallback when the flagship matches no row.
+ */
+
+'use strict';
+
+const { buildProviderDefaultChoices } = require('./provider-default-picker');
+const { pairAcrossGateways } = require('./gateway-route-catalog');
+
+/** Rows shown before the "all models" group. */
+const SHORTLIST_LIMIT = 8;
+
+/**
+ * Both gateway spellings of a row id, so a surface can honour an explicit
+ * "via OpenRouter" choice for a drilled-down model. NEVER derives one form
+ * from the other -- `pairAcrossGateways` reads real catalog rows, which is
+ * the only safe move for DIVERGENT_VENDORS (anthropic's direct and
+ * OpenRouter ids are different strings, not differently prefixed).
+ * @param {string} vendor
+ * @param {string} id verbatim picker row id
+ * @param {Array<{id:string}>} catalog
+ * @returns {{directId: (string|null), openrouterId: (string|null)}}
+ */
+function routeFormsFor(vendor, id, catalog) {
+  const token = id.replace(/^openrouter\//, '').replace(`${vendor}/`, '');
+  const paired = pairAcrossGateways(vendor, token, { models: catalog });
+  return {
+    directId: paired.direct || null,
+    openrouterId: paired.openrouter || null,
+  };
+}
+
+/**
+ * Recommended-first, then price-ascending, nulls last -- the same order
+ * `provider-default-picker.js`'s `compareRows` already establishes, so the
+ * drill-down reads like the picker the user may already have seen.
+ */
+function compareShortlistRows(a, b) {
+  if (a.isRecommended !== b.isRecommended) { return a.isRecommended ? -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;
+}
+
+/**
+ * @param {string} vendor e.g. 'deepseek'
+ * @param {{catalog?: Array<object>, recommendedId?: string, limit?: number}} [options]
+ * @returns {{recommendedId: (string|null), suggested: Array<object>,
+ *   rest: Array<object>, total: number}}
+ */
+function buildModelShortlist(vendor, options = {}) {
+  const catalog = Array.isArray(options.catalog) ? options.catalog : [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0
+    ? options.limit : SHORTLIST_LIMIT;
+
+  const { preselectedId, rows } = buildProviderDefaultChoices(vendor, { catalog });
+  if (!rows || rows.length === 0) {
+    return { recommendedId: null, suggested: [], rest: [], total: 0 };
+  }
+
+  // Owner ruling: the family flagship wins when it names a real row;
+  // otherwise keep the picker's tier preselect rather than inventing one.
+  const wanted = options.recommendedId;
+  const recommendedId = (wanted && rows.some(r => r.id === wanted)) ? wanted : preselectedId;
+
+  const annotated = rows.map(r => Object.assign({
+    id: r.id,
+    name: r.name,
+    contextLength: r.contextLength,
+    pricePerMInput: r.pricePerMInput,
+    isRecommended: r.id === recommendedId,
+  }, routeFormsFor(vendor, r.id, catalog)));
+
+  annotated.sort(compareShortlistRows);
+
+  return {
+    recommendedId,
+    suggested: annotated.slice(0, limit),
+    rest: annotated.slice(limit),
+    total: annotated.length,
+  };
+}
+
+module.exports = { buildModelShortlist, compareShortlistRows, SHORTLIST_LIMIT };