amicus 4.1.1 → 4.2.0

package/src/utils/quick-picks.js

@@ -10,7 +10,7 @@
 
 'use strict';
 
-const { getFamilies, toDefaultAliases, toCanonicalDefault } = require('./curated-models');
+const { getFamilies, toDefaultAliases, toCanonicalDefault, DIVERGENT_VENDORS } = require('./curated-models');
 
 const MARKER_RE = /(-preview|-exp|-beta|-latest|:free)+$/;
 
@@ -45,7 +45,7 @@ function pickCurrent(catalog, nsPrefix, vendorPath, idPattern) {
 
 /**
  * @param {Array<{id:string}>} catalog
- * @returns {Array<{alias,label,blurb,source:'live'|'fallback',routes:Object<string,string>}>}
+ * @returns {Array<{alias,label,blurb,vendorPath,source:'live'|'fallback',routes:Object<string,string>}>}
  * `routes` may be empty if a family defines no fallback and the catalog has no match.
  */
 function resolveQuickPicks(catalog) {
@@ -60,30 +60,53 @@ function resolveQuickPicks(catalog) {
       if (direct) { routes[p] = direct; live = true; }
       else if (f.fallback[p]) { routes[p] = f.fallback[p]; }
     }
-    return { alias: f.alias, label: f.label, blurb: f.blurb, routes,
+    return { alias: f.alias, label: f.label, blurb: f.blurb, vendorPath: f.vendorPath, routes,
              source: live ? 'live' : 'fallback' };
   });
 }
 
+/**
+ * The single route value a wizard may STORE for a resolved quick pick.
+ *
+ * For a direct-capable vendor the OpenRouter pick is canonicalised to bare
+ * `vendor/model` so it stays direct-first via the gateway router — otherwise a
+ * fresh `amicus setup` with a live catalog would silently defeat the
+ * direct-first default `toDefaultAliases()` establishes.
+ *
+ * For a DIVERGENT vendor the direct id is never DERIVED from the OpenRouter
+ * one: they are different strings, not differently prefixed (OpenRouter serves
+ * `anthropic/claude-opus-4.8`, the direct API `anthropic/claude-opus-4-8`).
+ * Stripping the prefix there fabricates an id the direct API rejects, which
+ * `amicus doctor` then reports as a stale alias. The row's own direct route is
+ * used verbatim, falling back to the intact `openrouter/` form when the
+ * catalog offered no direct pick. Mirrors the guard already used at
+ * `provider-default-picker.js:82,143,220`.
+ * @param {{vendorPath?:string, routes?:Object<string,string>}} pick
+ * @returns {string|undefined}
+ */
+function toStorableRoute(pick) {
+  const routes = (pick && pick.routes) || {};
+  if (pick && DIVERGENT_VENDORS.has(pick.vendorPath)) {
+    return routes[pick.vendorPath] || routes.openrouter;
+  }
+  return toCanonicalDefault(routes.openrouter || Object.values(routes)[0]);
+}
+
 /**
  * Seed map for fresh configs: static defaults overlaid with live family
- * routes (cardless aliases stay pinned). The overlaid route is run through
- * `toCanonicalDefault` so a direct-capable vendor (e.g. google, openai)
- * lands as bare `vendor/model` (direct-first via the gateway router)
- * instead of the raw `openrouter/<vendor>/<rest>` pick — otherwise a fresh
- * `amicus setup` with a live catalog would silently defeat the direct-first
- * default `toDefaultAliases()` establishes. Gateway-only vendors are
- * returned unchanged by `toCanonicalDefault`.
+ * routes (cardless aliases stay pinned). See `toStorableRoute` for why the
+ * overlaid value is not a raw prefix strip.
  * @returns {Object<string,string>}
  */
 function toLiveSeedAliases(catalog) {
   const seeds = toDefaultAliases();
   for (const r of resolveQuickPicks(catalog || [])) {
     if (r.source === 'live' && r.routes.openrouter) {
-      seeds[r.alias] = toCanonicalDefault(r.routes.openrouter);
+      const stored = toStorableRoute(r);
+      if (stored) { seeds[r.alias] = stored; }
     }
   }
   return seeds;
 }
 
-module.exports = { compareIdsDesc, pickCurrent, resolveQuickPicks, toLiveSeedAliases };
+module.exports = { compareIdsDesc, pickCurrent, resolveQuickPicks, toLiveSeedAliases, toStorableRoute };

package/src/utils/route-error.js

@@ -66,6 +66,9 @@ const REASON_TEXT = Object.freeze({
   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.",
+  no_openrouter_route: "Local providers can't be routed through OpenRouter.",
+  no_local_key: 'No bearer token is configured for this local provider.',
+  local_endpoint_unreachable: "The local endpoint didn't respond.",
   [SELECTION_REQUIRED_REASON]: 'Multiple models match your request; a specific one must be selected.',
 });
 
@@ -80,6 +83,9 @@ const FIX_HINTS = Object.freeze({
   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.',
+  no_openrouter_route: 'Drop --gateway openrouter — local endpoints route direct.',
+  no_local_key: 'Add one with `amicus key <id> <token>`.',
+  local_endpoint_unreachable: 'Start the local server, or pass --no-validate-model to skip the reachability check.',
   [SELECTION_REQUIRED_REASON]: 'Pick one of the suggestions below, or narrow the model id.',
 });
 
@@ -139,7 +145,7 @@ function toCliMessage(result) {
     }
   }
 
-  const hint = FIX_HINTS[err.reason];
+  const hint = (result && result.hint) || FIX_HINTS[err.reason];
   if (hint) { lines.push(hint); }
 
   return lines.join('\n');
@@ -156,7 +162,8 @@ function toCliMessage(result) {
  */
 function toErrorDocFields(result) {
   const { ERROR_CODES } = require('./error-doc');
-  const KEY_REASONS = ['no_openrouter_key', 'no_direct_key', 'no_key_for_vendor'];
+  // v4.2: a missing local bearer is key-shaped, not model-shaped (D12).
+  const KEY_REASONS = ['no_openrouter_key', 'no_direct_key', 'no_key_for_vendor', 'no_local_key'];
   const err = toStructuredError(result);
   const sentence = REASON_TEXT[err.reason] || `Model routing error (${err.reason}).`;
   let message = err.requested ? `${sentence} (requested "${err.requested}")` : sentence;
@@ -166,7 +173,7 @@ function toErrorDocFields(result) {
   return {
     code: KEY_REASONS.includes(err.reason) ? ERROR_CODES.MISSING_KEY : ERROR_CODES.BAD_MODEL,
     message,
-    hint: FIX_HINTS[err.reason] || null,
+    hint: (result && result.hint) || FIX_HINTS[err.reason] || null,
   };
 }
 

package/src/utils/route-launch.js

@@ -11,6 +11,7 @@
 const { readApiKeys } = require('./api-key-store');
 const { readAuthJsonKeys } = require('./auth-json');
 const { KNOWN_PROVIDERS } = require('./provider-registry');
+const { buildSuggestions, applySuggestions } = require('./route-suggestions');
 
 /**
  * Per-provider key presence across BOTH sources: env/.env (readApiKeys) and
@@ -50,69 +51,6 @@ async function getRouteCatalogInfo() {
 /** Module version stamped onto `resolved` results' provenance (carry-forward). */
 const ROUTE_VERSION = 1;
 
-/**
- * Build up to ~6 labeled alternatives for a `selection_required` RouteResult
- * (#61 Task 6.3, spec Decision 10). Pure: reads only the already-parsed
- * descriptor plus the live keys/catalogInfo/gatewayIds the caller already
- * assembled.
- *
- * Two categories, in order:
- *  1. The SAME model via OpenRouter — only when an OpenRouter key is present
- *     AND the OR-namespaced id is actually present in the catalog (never
- *     suggest an id we can't confirm exists). For divergent vendors (e.g.
- *     Anthropic) `descriptor.model` may be the DASH-form direct id, so a
- *     reconstructed `openrouter/<vendor>/<model>` would never match the
- *     catalog's dot-form OR id -- when the caller's `gatewayIds.openrouter`
- *     is available (the catalog-correct form), it is used instead of
- *     reconstructing. Falls back to reconstruction when `gatewayIds` is
- *     absent (non-alias / full-id / non-divergent requests), so behavior
- *     there is unchanged.
- *  2. Up to 5 OTHER models in the same direct vendor namespace (ids starting
- *     `<vendor>/`, excluding the requested id itself and excluding any
- *     `openrouter/`-prefixed rows, which share the `<vendor>/` prefix check
- *     only when vendor === 'openrouter' and are filtered out defensively).
- *
- * @param {{vendor?: string, model?: string}} descriptor parsed Descriptor for
- *   the request that produced the selection_required (canonical or
- *   openrouter-literal — both carry vendor/model)
- * @param {Object<string,boolean>} keys per-provider key-presence map (buildLaunchKeys() shape)
- * @param {{models: Array<{id:string}>}} catalogInfo
- * @param {{direct?: string, openrouter?: string}} [gatewayIds] the same
- *   per-gateway id map resolveRouteForLaunch threads through resolveRoute
- *   (Task 3's bridge for divergent curated aliases); absent for non-alias /
- *   full-id / non-divergent requests
- * @returns {Array<{model:string, gateway:string, note:string}>}
- */
-function buildSuggestions(descriptor, keys, catalogInfo, gatewayIds) {
-  const suggestions = [];
-  const vendor = descriptor && descriptor.vendor;
-  const model = descriptor && descriptor.model;
-  if (!vendor || !model) { return suggestions; }
-
-  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
-  const requestedDirectId = `${vendor}/${model}`;
-
-  if (keys && keys.openrouter) {
-    const orId = (gatewayIds && gatewayIds.openrouter) || `openrouter/${vendor}/${model}`;
-    if (models.some(m => m && m.id === orId)) {
-      suggestions.push({ model: orId, gateway: 'openrouter', note: 'same model via OpenRouter' });
-    }
-  }
-
-  const nsPrefix = `${vendor}/`;
-  const sameVendor = models.filter(m =>
-    m && typeof m.id === 'string' &&
-    m.id.startsWith(nsPrefix) &&
-    !m.id.startsWith('openrouter/') &&
-    m.id !== requestedDirectId
-  ).slice(0, 5);
-  for (const m of sameVendor) {
-    suggestions.push({ model: m.id, gateway: 'direct', note: `${vendor} model` });
-  }
-
-  return suggestions.slice(0, 6);
-}
-
 /**
  * One-time per-vendor notice when auto-routing migrates a both-key holder off
  * OpenRouter onto direct (#61 Task 5.1 — visible-migration guarantee: never
@@ -286,12 +224,17 @@ async function resolveRouteForLaunch({ model, gatewayMode, source, allowSelectio
     }
   }
   const descriptor = parseDescriptor(concrete, { aliases });
-  let result = resolveRoute({ descriptor, source, gatewayMode, allowSelection, validateModel, keys, catalogInfo, gatewayIds });
+  // v4.2: local-provider inputs (assembled in local-providers.js — 300-line gate).
+  const { getLocalProviders, resolveLocalRouteInputs } = require('./local-providers');
+  const { localProviders, localLive } =
+    await resolveLocalRouteInputs(descriptor, { validateModel, providers: getLocalProviders() });
+  let result = resolveRoute({ descriptor, source, gatewayMode, allowSelection, validateModel,
+    keys, catalogInfo, gatewayIds, localProviders, localLive });
   if (result.kind === 'resolved') {
     result.provenance = { ...result.provenance, resolutionVersion: ROUTE_VERSION };
     result = maybeMigrationNotice({ result, descriptor, gatewayMode, keys });
   } else if (result.kind === 'selection_required') {
-    result.suggestions = buildSuggestions(descriptor, keys, catalogInfo, gatewayIds);
+    applySuggestions(result, { descriptor, keys, catalogInfo, gatewayIds, localProviders });
   }
   return result;
 }

package/src/utils/route-suggestions.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Suggestion-building for `selection_required` RouteResults, split out of
+ * route-launch.js (B2/D3 — the 300-line gate). Pure: no I/O, no requires.
+ */
+
+/**
+ * Build up to ~6 labeled alternatives for a `selection_required` RouteResult
+ * (#61 Task 6.3, spec Decision 10). Pure: reads only the already-parsed
+ * descriptor plus the live keys/catalogInfo/gatewayIds the caller already
+ * assembled.
+ *
+ * Two categories, in order:
+ *  1. The SAME model via OpenRouter — only when an OpenRouter key is present
+ *     AND the OR-namespaced id is actually present in the catalog (never
+ *     suggest an id we can't confirm exists). For divergent vendors (e.g.
+ *     Anthropic) `descriptor.model` may be the DASH-form direct id, so a
+ *     reconstructed `openrouter/<vendor>/<model>` would never match the
+ *     catalog's dot-form OR id -- when the caller's `gatewayIds.openrouter`
+ *     is available (the catalog-correct form), it is used instead of
+ *     reconstructing. Falls back to reconstruction when `gatewayIds` is
+ *     absent (non-alias / full-id / non-divergent requests), so behavior
+ *     there is unchanged.
+ *  2. Up to 5 OTHER models in the same direct vendor namespace (ids starting
+ *     `<vendor>/`, excluding the requested id itself and excluding any
+ *     `openrouter/`-prefixed rows, which share the `<vendor>/` prefix check
+ *     only when vendor === 'openrouter' and are filtered out defensively).
+ *
+ * @param {{vendor?: string, model?: string}} descriptor parsed Descriptor for
+ *   the request that produced the selection_required (canonical or
+ *   openrouter-literal — both carry vendor/model)
+ * @param {Object<string,boolean>} keys per-provider key-presence map (buildLaunchKeys() shape)
+ * @param {{models: Array<{id:string}>}} catalogInfo
+ * @param {{direct?: string, openrouter?: string}} [gatewayIds] the same
+ *   per-gateway id map resolveRouteForLaunch threads through resolveRoute
+ *   (Task 3's bridge for divergent curated aliases); absent for non-alias /
+ *   full-id / non-divergent requests
+ * @returns {Array<{model:string, gateway:string, note:string}>}
+ */
+function buildSuggestions(descriptor, keys, catalogInfo, gatewayIds) {
+  const suggestions = [];
+  const vendor = descriptor && descriptor.vendor;
+  const model = descriptor && descriptor.model;
+  if (!vendor || !model) { return suggestions; }
+
+  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
+  const requestedDirectId = `${vendor}/${model}`;
+
+  if (keys && keys.openrouter) {
+    const orId = (gatewayIds && gatewayIds.openrouter) || `openrouter/${vendor}/${model}`;
+    if (models.some(m => m && m.id === orId)) {
+      suggestions.push({ model: orId, gateway: 'openrouter', note: 'same model via OpenRouter' });
+    }
+  }
+
+  const nsPrefix = `${vendor}/`;
+  const sameVendor = models.filter(m =>
+    m && typeof m.id === 'string' &&
+    m.id.startsWith(nsPrefix) &&
+    !m.id.startsWith('openrouter/') &&
+    m.id !== requestedDirectId
+  ).slice(0, 5);
+  for (const m of sameVendor) {
+    suggestions.push({ model: m.id, gateway: 'direct', note: `${vendor} model` });
+  }
+
+  return suggestions.slice(0, 6);
+}
+
+/**
+ * v4.2 (D10/M24): apply catalog-derived suggestions to a `selection_required`
+ * result — EXCEPT for a local vendor, whose suggestions the router already
+ * built from the live probe (spec §4.2 point 4: "suggestions = the live list,
+ * capped at 6"). buildSuggestions reads only `catalogInfo.models` (the 24 h
+ * cache, never `req.localLive`) and hardcodes `gateway:'direct'`, so letting it
+ * overwrite a local result ships stale-or-empty rows under the wrong label.
+ * @param {Object} result the `selection_required` RouteResult, mutated in place
+ */
+function applySuggestions(result, { descriptor, keys, catalogInfo, gatewayIds, localProviders }) {
+  if (localProviders && descriptor && Object.prototype.hasOwnProperty.call(localProviders, descriptor.vendor)) { return; }
+  result.suggestions = buildSuggestions(descriptor, keys, catalogInfo, gatewayIds);
+}
+
+module.exports = { buildSuggestions, applySuggestions };