amicus 3.0.0 → 3.1.0

package/src/utils/gateway-router.js

@@ -0,0 +1,115 @@
+/**
+ * Pure gateway router (#61). Decides direct vs OpenRouter for a request using
+ * only injected state (keys, catalogInfo, gatewayMode) — no I/O. Returns a
+ * RouteResult (resolved | selection_required | error). Wiring into launch paths
+ * is Plan 2; this module is behavior-neutral until then.
+ */
+'use strict';
+
+const { resolved, routeError, selectionRequired, parseDescriptor } = require('./model-descriptor');
+const { classifyModel } = require('./model-classification');
+const { isDirectProvider } = require('./provider-registry');
+
+/** Build the executable id for a gateway. */
+function executableFor(gateway, vendor, model) {
+  return gateway === 'openrouter' ? `openrouter/${vendor}/${model}` : `${vendor}/${model}`;
+}
+
+/**
+ * Catalog gate: returns { ok:true, notice? } to proceed, or { ok:false, result }
+ * carrying a selection_required/error to return to the caller.
+ */
+function catalogGate({ id, gateway, req }) {
+  if (req.validateModel === false) {
+    return { ok: true, notice: 'Model availability not validated (--no-validate-model).' };
+  }
+  const verdict = classifyModel(id, gateway, req.catalogInfo);
+  if (verdict === 'valid') { return { ok: true }; }
+  if (verdict === 'unknown') {
+    return { ok: true, notice: `Model '${id}' is unverified against the ${gateway} catalog; attempting anyway.` };
+  }
+  // invalid
+  if (req.allowSelection) {
+    return { ok: false, result: selectionRequired({ requested: req.descriptor.raw, suggestions: [] }) };
+  }
+  return { ok: false, result: routeError({ requested: req.descriptor.raw, reason: 'model_not_found',
+    preferredGateway: gateway, suggestions: [] }) };
+}
+
+/** Resolve to a concrete gateway after the catalog gate passes. */
+function finish(gateway, vendor, model, req) {
+  const id = executableFor(gateway, vendor, model);
+  const gate = catalogGate({ id, gateway, req });
+  if (!gate.ok) { return gate.result; }
+  return resolved({ model: id, gateway, executableId: id,
+    provenance: { source: req.source, requested: req.descriptor.raw, gatewayMode: req.gatewayMode }, notice: gate.notice });
+}
+
+/**
+ * @param {object} req see Task 5 Interfaces
+ * @returns RouteResult
+ */
+function resolveRoute(req) {
+  // 1. Normalize: req.descriptor may arrive as a parsed Descriptor object or a
+  // raw canonical/OR-literal id string. Only canonical/openrouter-literal kinds
+  // are routable; alias/invalid/garbage descriptors are rejected right here,
+  // before any branch below touches vendor/model. All downstream code reads
+  // from the normalized `d` (via the cloned `rq`), never from req.descriptor.
+  let d = req.descriptor;
+  if (typeof d === 'string') {
+    d = parseDescriptor(d, { aliases: {} });
+  }
+  if (!d || (d.kind !== 'canonical' && d.kind !== 'openrouter-literal')) {
+    const requested = d ? d.raw : (typeof req.descriptor === 'string' ? req.descriptor : String(req && req.descriptor));
+    return routeError({ requested, reason: 'invalid_descriptor', preferredGateway: req.gatewayMode, suggestions: [] });
+  }
+  const rq = { ...req, descriptor: d };
+  const vendor = d.vendor;
+  const model = d.model;
+
+  // 2. Explicit conflict: force-OR literal vs --gateway direct
+  if (d.isExplicitOpenRouter && rq.gatewayMode === 'direct') {
+    return routeError({ requested: d.raw, reason: 'gateway_conflict', preferredGateway: 'direct', suggestions: [] });
+  }
+  // 3. Explicit OR literal
+  if (d.isExplicitOpenRouter) {
+    if (!rq.keys.openrouter) {
+      return routeError({ requested: d.raw, reason: 'no_openrouter_key', preferredGateway: 'openrouter', suggestions: [] });
+    }
+    return finish('openrouter', vendor, model, rq);
+  }
+  // 4. Gateway-only vendor (no direct integration)
+  if (!isDirectProvider(vendor)) {
+    if (rq.gatewayMode === 'direct') {
+      return routeError({ requested: d.raw, reason: 'no_direct_integration', preferredGateway: 'direct', suggestions: [] });
+    }
+    if (!rq.keys.openrouter) {
+      return routeError({ requested: d.raw, reason: 'no_openrouter_key', preferredGateway: 'openrouter', suggestions: [] });
+    }
+    return finish('openrouter', vendor, model, rq);
+  }
+  // 5. Explicit --gateway openrouter
+  if (rq.gatewayMode === 'openrouter') {
+    if (!rq.keys.openrouter) {
+      return routeError({ requested: d.raw, reason: 'no_openrouter_key', preferredGateway: 'openrouter', suggestions: [] });
+    }
+    return finish('openrouter', vendor, model, rq);
+  }
+  // 6. Explicit --gateway direct
+  if (rq.gatewayMode === 'direct') {
+    if (!rq.keys[vendor]) {
+      return routeError({ requested: d.raw, reason: 'no_direct_key', preferredGateway: 'direct', suggestions: [] });
+    }
+    return finish('direct', vendor, model, rq);
+  }
+  // 7. auto (direct-first)
+  if (rq.keys[vendor]) {
+    return finish('direct', vendor, model, rq);
+  }
+  if (rq.keys.openrouter) {
+    return finish('openrouter', vendor, model, rq);
+  }
+  return routeError({ requested: d.raw, reason: 'no_key_for_vendor', preferredGateway: 'direct', suggestions: [] });
+}
+
+module.exports = { resolveRoute };

package/src/utils/input-validators.js

@@ -3,7 +3,8 @@
 /**
  * @module input-validators
  * MCP input validation with structured error responses.
- * Composes validators from validators.js and adds model resolution.
+ * Composes validators from validators.js for prompt/timeout/agent checks.
+ * Model resolution/routing lives in mcp-server.js (#61 Task 6.2), not here.
  */
 
 // Lazy require to avoid circular dependency (validators.js re-exports from here)
@@ -13,26 +14,15 @@ function getValidators() {
   return _validators;
 }
 
-/**
- * Find candidates that start with the input or vice versa.
- * @param {string} input
- * @param {string[]} candidates
- * @returns {string[]} Up to 3 matching candidates
- */
-function findSimilar(input, candidates) {
-  if (!input) { return []; }
-  const lower = input.toLowerCase();
-  return candidates.filter(c => {
-    const cl = c.toLowerCase();
-    return cl.startsWith(lower) || lower.startsWith(cl);
-  }).slice(0, 3);
-}
-
 /**
  * Validate sidecar_start inputs before session creation.
- * Composes existing validators and adds model resolution.
+ * Composes existing validators for prompt/timeout/agent. Model resolution is
+ * NOT this function's concern (#61 Task 6.2): it is routed separately by the
+ * mcp-server.js amicus_start handler via resolveRouteForLaunch, so a routing
+ * failure can be rendered as a structured `model_route_error` (parity with the
+ * CLI's resolveLaunchModel) rather than the `validation_error` shape below.
  * @param {Object} input - Raw MCP tool input
- * @returns {{ valid: true, resolvedModel: string } | { valid: false, error: Object }}
+ * @returns {{ valid: true } | { valid: false, error: Object }}
  */
 function validateStartInputs(input) {
   // 1. Prompt
@@ -49,27 +39,7 @@ function validateStartInputs(input) {
     };
   }
 
-  // 2. Model: resolve alias to full provider/model string
-  const { tryResolveModel, getEffectiveAliases } = require('./config');
-  const { model: resolved, error: modelError } = tryResolveModel(input.model);
-  if (modelError) {
-    const aliases = Object.keys(getEffectiveAliases());
-    const suggestions = findSimilar(input.model, aliases);
-    return {
-      valid: false,
-      error: {
-        type: 'validation_error',
-        field: 'model',
-        message: input.model
-          ? `Model '${input.model}' not found. ${modelError}`
-          : `No model specified and no default configured. ${modelError}`,
-        suggestions,
-        available: aliases,
-      },
-    };
-  }
-
-  // 3. Timeout: positive number, max 60 minutes
+  // 2. Timeout: positive number, max 60 minutes
   if (input.timeout !== undefined) {
     const t = Number(input.timeout);
     if (isNaN(t) || t <= 0) {
@@ -94,7 +64,7 @@ function validateStartInputs(input) {
     }
   }
 
-  // 4. Agent + headless compatibility
+  // 3. Agent + headless compatibility
   // Note: MCP Zod schema defaults agent to 'Chat'. The handler auto-converts
   // Chat to Build for headless mode (line ~92 in mcp-server.js). Only reject
   // if the user explicitly set agent to Chat with noUi (not the Zod default).
@@ -121,7 +91,7 @@ function validateStartInputs(input) {
     }
   }
 
-  return { valid: true, resolvedModel: resolved };
+  return { valid: true };
 }
 
 /**
@@ -175,4 +145,4 @@ function suggestCommand(input, candidates, maxDistance = 2, maxSuggestions = 3)
     .map(({ c }) => c);
 }
 
-module.exports = { validateStartInputs, findSimilar, levenshteinDistance, suggestCommand };
+module.exports = { validateStartInputs, levenshteinDistance, suggestCommand };

package/src/utils/model-classification.js

@@ -0,0 +1,65 @@
+/**
+ * Tri-state catalog classification (#61).
+ * Turns the combined catalog + refresh outcome into valid|invalid|unknown for a
+ * (model, gateway) pair. `unknown` NEVER rejects a route — it preserves the
+ * existing "empty catalog cannot validate, never block a launch" contract.
+ *
+ * Namespace matching is scoped PER-VENDOR, not by a flat openrouter/direct
+ * split. The combined catalog always contains a hardcoded Anthropic floor, so
+ * a flat "direct" namespace is never empty even when a specific vendor's rows
+ * were never fetched (e.g. that provider's /models call was stale or failed).
+ * Matching per-vendor means a missing vendor's rows correctly yield `unknown`
+ * instead of being masked by the always-present floor rows of another vendor.
+ *
+ * - gateway === 'direct': vendor = id.split('/')[0]; namespace prefix is
+ *   `${vendor}/`, restricted to rows NOT under `openrouter/`.
+ * - gateway === 'openrouter': id looks like `openrouter/<vendor>/<model>`, so
+ *   vendor = id.split('/')[1]; namespace prefix is `openrouter/${vendor}/`.
+ *
+ * Non-authoritative rows (`authoritative: false`, e.g. the hardcoded Anthropic
+ * floor-fallback tagged by model-fetcher.js when a keyed live fetch fails or no
+ * key is present — see fetchModelsFromProvider('anthropic', key)) cannot assert
+ * absence either: if EVERY row in the matched namespace is non-authoritative and
+ * the exact id is not among them, a miss returns `unknown`, not `invalid` — the
+ * floor is a stale/synthesized list, not a confirmed model roster, so it must
+ * never hard-block a launch (#61 4.3). A namespace containing at least one
+ * authoritative (live-fetched) row still yields `invalid` on a genuine miss.
+ *
+ * Pure: the caller passes catalogInfo (from model-catalog.getCatalogInfo()).
+ * @param {string} id       exact model id as the user gave it
+ * @param {'direct'|'openrouter'} gateway  which namespace to match against
+ * @param {{models: Array<{id:string, authoritative?: boolean}>, lastRefreshError?: string|null}} catalogInfo
+ * @returns {'valid'|'invalid'|'unknown'}
+ */
+function classifyModel(id, gateway, catalogInfo) {
+  const models = (catalogInfo && Array.isArray(catalogInfo.models)) ? catalogInfo.models : [];
+  if (models.length === 0) { return 'unknown'; }
+
+  const idParts = typeof id === 'string' ? id.split('/') : [];
+  const isOpenRouter = gateway === 'openrouter';
+  const vendor = isOpenRouter ? idParts[1] : idParts[0];
+  const nsPrefix = isOpenRouter ? `openrouter/${vendor}/` : `${vendor}/`;
+
+  const inNamespace = (mid) => {
+    if (typeof mid !== 'string' || !mid.startsWith(nsPrefix)) { return false; }
+    return isOpenRouter ? true : !mid.startsWith('openrouter/');
+  };
+  const namespaceRows = models.filter(m => m && typeof m.id === 'string' && inNamespace(m.id));
+
+  // No rows for this vendor's namespace -> we cannot assert absence (e.g. that
+  // provider's key is absent so its rows were never fetched, or a partial
+  // refresh). Unknown — never block on a namespace we couldn't populate.
+  if (namespaceRows.length === 0) { return 'unknown'; }
+
+  const present = namespaceRows.some(m => m.id === id);
+  if (present) { return 'valid'; }
+
+  // Every matched row is a non-authoritative floor-fallback row (never live-
+  // fetched) -> a miss cannot be trusted as a confirmed absence. Never block.
+  const allNonAuthoritative = namespaceRows.every(m => m.authoritative === false);
+  if (allNonAuthoritative) { return 'unknown'; }
+
+  return 'invalid';
+}
+
+module.exports = { classifyModel };

package/src/utils/model-descriptor.js

@@ -0,0 +1,72 @@
+/**
+ * Model-descriptor grammar + RouteResult factories (#61).
+ * Pure string classification — no I/O, no provider lookups. The resolver
+ * (gateway-router.js) consumes Descriptors and returns RouteResults.
+ */
+'use strict';
+
+const GATEWAY_MODES = ['auto', 'direct', 'openrouter'];
+const OR_PREFIX = 'openrouter/';
+
+/**
+ * Classify a raw model string into a normalized descriptor.
+ * Grammar:
+ *   - `openrouter/<vendor>/<model>`  -> openrouter-literal (explicit force-OR)
+ *   - `<vendor>/<model...>`          -> canonical (policy-routed)
+ *   - known no-slash alias            -> alias (resolution deferred to caller)
+ *   - anything else                   -> invalid (incl. unknown no-slash token)
+ * @param {string} raw
+ * @param {{aliases: Object<string,string>}} ctx
+ * @returns {{raw:string, kind:string, vendor?:string, model?:string, isExplicitOpenRouter:boolean, error?:string}}
+ */
+function parseDescriptor(raw, ctx = {}) {
+  const aliases = ctx.aliases || {};
+  const trimmed = typeof raw === 'string' ? raw.trim() : '';
+  if (!trimmed) {
+    return { raw, kind: 'invalid', isExplicitOpenRouter: false, error: 'Empty model identifier' };
+  }
+  if (trimmed.startsWith(OR_PREFIX)) {
+    const rest = trimmed.slice(OR_PREFIX.length);
+    const parts = rest.split('/');
+    if (parts.length < 2 || !parts[0] || !parts.slice(1).join('/')) {
+      return { raw: trimmed, kind: 'invalid', isExplicitOpenRouter: true,
+        error: `Malformed OpenRouter model id '${trimmed}' (expected openrouter/vendor/model)` };
+    }
+    return { raw: trimmed, kind: 'openrouter-literal', vendor: parts[0],
+      model: parts.slice(1).join('/'), isExplicitOpenRouter: true };
+  }
+  if (trimmed.includes('/')) {
+    const parts = trimmed.split('/');
+    if (parts.length < 2 || !parts[0] || !parts.slice(1).join('/')) {
+      return { raw: trimmed, kind: 'invalid', isExplicitOpenRouter: false,
+        error: `Malformed model id '${trimmed}' (expected vendor/model)` };
+    }
+    return { raw: trimmed, kind: 'canonical', vendor: parts[0],
+      model: parts.slice(1).join('/'), isExplicitOpenRouter: false };
+  }
+  if (Object.prototype.hasOwnProperty.call(aliases, trimmed)) {
+    return { raw: trimmed, kind: 'alias', isExplicitOpenRouter: false };
+  }
+  return { raw: trimmed, kind: 'invalid', isExplicitOpenRouter: false,
+    error: `Unknown model alias '${trimmed}'. Run 'amicus setup' to configure aliases, or use a vendor/model id.` };
+}
+
+/** @returns {{kind:'resolved', model:string, gateway:string, executableId:string, provenance:object, notice?:string}} */
+function resolved({ model, gateway, executableId, provenance, notice }) {
+  const out = { kind: 'resolved', model, gateway, executableId, provenance: provenance || {} };
+  if (notice) { out.notice = notice; }
+  return out;
+}
+
+/** @returns {{kind:'selection_required', requested:string, suggestions:Array}} */
+function selectionRequired({ requested, suggestions }) {
+  return { kind: 'selection_required', requested, suggestions: suggestions || [] };
+}
+
+/** @returns {{kind:'error', type:'model_route_error', ...}} */
+function routeError({ field, requested, reason, preferredGateway, suggestions }) {
+  return { kind: 'error', type: 'model_route_error', field: field || 'model',
+    requested, reason, preferredGateway, suggestions: suggestions || [] };
+}
+
+module.exports = { GATEWAY_MODES, parseDescriptor, resolved, selectionRequired, routeError };

package/src/utils/model-fetcher.js

@@ -16,13 +16,7 @@ const ANTHROPIC_MODELS = [
   { id: 'anthropic/claude-3-5-haiku', name: 'Claude 3.5 Haiku', contextLength: null, pricing: null }
 ];
 
-const PROVIDER_FAMILY_NAMES = {
-  openrouter: 'OpenRouter',
-  google: 'Google',
-  openai: 'OpenAI',
-  anthropic: 'Anthropic',
-  deepseek: 'DeepSeek'
-};
+const { PROVIDER_FAMILY_NAMES } = require('./provider-registry');
 
 /** Provider API configs for fetching model lists */
 const PROVIDER_FETCH_CONFIG = {
@@ -82,7 +76,20 @@ const PROVIDER_FETCH_CONFIG = {
         pricing: null
       }));
     }
-  }
+  },
+  anthropic: {
+    url: 'https://api.anthropic.com/v1/models',
+    authHeader: (key) => ({ 'x-api-key': key, 'anthropic-version': '2023-06-01' }),
+    normalize: (body) => {
+      const data = JSON.parse(body);
+      return (data.data || []).map(m => ({
+        id: `anthropic/${m.id}`,
+        name: m.display_name || m.id,
+        contextLength: null,
+        pricing: null,
+      }));
+    },
+  },
 };
 
 const FETCH_TIMEOUT_MS = 5000;
@@ -95,7 +102,14 @@ const FETCH_TIMEOUT_MS = 5000;
  */
 function fetchModelsFromProvider(provider, key) {
   if (provider === 'anthropic') {
-    return Promise.resolve(ANTHROPIC_MODELS);
+    // No key -> hardcoded floor, no network. With a key -> try live, fall back to floor.
+    // Floor-fallback rows are tagged authoritative:false (#61 4.3) so classifyModel
+    // never hard-blocks a miss against a stale/hardcoded list -- it returns
+    // 'unknown' instead. Rows from a successful live fetch are NOT tagged (they
+    // are authoritative). Map to new objects; never mutate ANTHROPIC_MODELS in place.
+    if (!key) { return Promise.resolve(ANTHROPIC_MODELS.map(r => ({ ...r, authoritative: false }))); }
+    return fetchViaConfig('anthropic', key).then(rows =>
+      (rows.length > 0 ? rows : ANTHROPIC_MODELS.map(r => ({ ...r, authoritative: false }))));
   }
 
   const config = PROVIDER_FETCH_CONFIG[provider];
@@ -103,6 +117,18 @@ function fetchModelsFromProvider(provider, key) {
     return Promise.resolve([]);
   }
 
+  return fetchViaConfig(provider, key);
+}
+
+/**
+ * Perform the HTTPS fetch + normalize for a single configured provider.
+ * Resolves to `[]` on any non-200 response, network error, timeout, or parse error.
+ * @param {string} provider - Key into PROVIDER_FETCH_CONFIG
+ * @param {string} key - API key
+ * @returns {Promise<Array>} Normalized model rows, or [] on any failure
+ */
+function fetchViaConfig(provider, key) {
+  const config = PROVIDER_FETCH_CONFIG[provider];
   const url = config.buildUrl ? config.buildUrl(key) : config.url;
   const headers = config.authHeader(key);
 

package/src/utils/model-input-default.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * @module model-input-default
+ * Shared "no --model given" default-lookup, extracted so it lives in exactly
+ * one place (#61 Task 6.2 review follow-up): both the CLI's resolveLaunchModel
+ * (start-helpers.js) and the MCP amicus_start handler (mcp-server.js) need to
+ * fall back to the configured default before handing a model off to
+ * resolveRouteForLaunch — without it, an omitted model reaches
+ * resolveRouteForLaunch as undefined -> parseDescriptor(undefined) -> an
+ * `invalid` descriptor, breaking the common "no --model" launch case.
+ * A leaf module (no other src/ module requires/mocks it), so introducing it
+ * doesn't reshape any existing jest.doMock('../src/utils/route-launch', ...)
+ * or jest.doMock('../src/utils/config', ...) call shape.
+ */
+
+/**
+ * Resolve the raw model input for a launch: an explicit value (including one
+ * a caller may have already normalized) passes through unchanged; otherwise
+ * falls back to the configured default.
+ * @param {string|null|undefined} inputModel
+ * @returns {string|undefined} inputModel as-is, the configured default, or
+ *   undefined if neither exists (the caller decides how to report that).
+ */
+function resolveModelInputOrDefault(inputModel) {
+  if (inputModel !== undefined && inputModel !== null) { return inputModel; }
+  const { loadConfig } = require('./config');
+  const cfg = loadConfig();
+  return (cfg && cfg.default) ? cfg.default : undefined;
+}
+
+module.exports = { resolveModelInputOrDefault };

package/src/utils/model-validator.js

@@ -7,10 +7,7 @@
  */
 
 const readline = require('readline');
-const { fetchModelsFromProvider } = require('./model-fetcher');
-const { readApiKeyValues } = require('./api-key-store');
 const { loadConfig, saveConfig, getConfigPath } = require('./config');
-const { logger } = require('./logger');
 
 /**
  * Normalize a model ID to include the provider prefix.
@@ -33,54 +30,6 @@ const ALIAS_SEARCH_TERMS = {
   'deepseek': 'deepseek',
 };
 
-/**
- * Validate a direct-API fallback model exists on the provider.
- * Returns silently if valid. On failure: prompts (interactive) or throws (headless).
- *
- * @param {string} resolvedModel - e.g. 'google/gemini-3.1-flash-lite-preview'
- * @param {string} alias - Original alias name (e.g. 'gemini')
- * @param {object} [options]
- * @param {boolean} [options.headless] - If true, throw instead of prompting
- * @returns {Promise<string>} Confirmed model string
- */
-async function validateDirectModel(resolvedModel, alias, options = {}) {
-  const parts = resolvedModel.split('/');
-  if (parts.length < 2) { return resolvedModel; }
-
-  const provider = parts[0];
-  const modelId = parts.slice(1).join('/');
-
-  const keys = readApiKeyValues();
-  const providerKey = keys[provider];
-  if (!providerKey) { return resolvedModel; }
-
-  let models;
-  try {
-    models = await fetchModelsFromProvider(provider, providerKey);
-  } catch (err) {
-    logger.debug({ msg: 'Model fetch failed, skipping validation', error: err.message });
-    return resolvedModel;
-  }
-
-  if (!models || models.length === 0) { return resolvedModel; }
-
-  const found = models.some(m => m.id === resolvedModel || m.id === modelId);
-  if (found) { return resolvedModel; }
-
-  const relevant = filterRelevantModels(models, alias);
-
-  if (options.headless || !process.stdin.isTTY) {
-    const list = relevant.slice(0, 10).map(m => `  ${normalizeModelId(provider, m.id)}`).join('\n');
-    throw new Error(
-      `Model '${modelId}' not found on ${provider} API.\n` +
-      `Available models:\n${list}\n` +
-      `Fix with: amicus setup --add-alias ${alias}=${relevant[0] ? normalizeModelId(provider, relevant[0].id) : 'provider/model'}`
-    );
-  }
-
-  return promptModelSelection(relevant, alias, provider, modelId);
-}
-
 /**
  * Filter models to those relevant to the alias
  * @param {Array<{id: string, name: string}>} models
@@ -101,54 +50,83 @@ function filterRelevantModels(models, alias) {
   return filtered.slice(0, 15);
 }
 
-/** Interactive prompt — ask user to pick from available models */
-async function promptModelSelection(models, alias, provider, failedModelId) {
-  process.stderr.write(`\n  Model '${failedModelId}' not found on ${provider} API.\n`);
-  process.stderr.write('  Available models:\n');
-  models.forEach((m, i) => {
-    const label = (m.name && m.name !== m.id) ? `${m.name} (${m.id})` : m.id;
-    process.stderr.write(`    ${i + 1}. ${label}\n`);
+/**
+ * Interactive alternatives picker for a direct-model miss (#61 Task 6.3, spec
+ * Decision 10). Presents `selectionResult.suggestions` (built upstream by
+ * route-launch.js's buildSuggestions) as a labeled numbered menu and lets the
+ * user pick one, or cancel. Uses the same readline + persist pattern (same
+ * save-with-malformed-config guard) as other model pickers in this module,
+ * adapted to the `{model, gateway, note}` suggestion shape instead of
+ * provider `{id, name}` rows.
+ *
+ * Never auto-selects — even a single suggestion still requires an explicit
+ * pick. Cancellation (empty input, an out-of-range number, or no suggestions
+ * to offer) always throws; the caller (resolveLaunchModel) is expected to
+ * catch and translate that into a "cancelled" stderr message + exit(1).
+ *
+ * @param {{requested: string, suggestions: Array<{model:string, gateway:string, note?:string}>}} selectionResult
+ * @param {string|undefined} alias - alias to persist the choice under, if any
+ * @returns {Promise<{model: string, gateway: string}>}
+ */
+async function promptRouteSelection(selectionResult, alias) {
+  const suggestions = (selectionResult && Array.isArray(selectionResult.suggestions))
+    ? selectionResult.suggestions : [];
+  const requested = selectionResult && selectionResult.requested;
+
+  process.stderr.write(`\n  Model '${requested}' isn't available on the direct API.\n`);
+
+  if (suggestions.length === 0) {
+    process.stderr.write('  No alternatives available.\n\n');
+    throw new Error('Model selection cancelled.');
+  }
+
+  process.stderr.write('  Alternatives:\n');
+  suggestions.forEach((s, i) => {
+    const note = s && s.note ? ` — ${s.note}` : '';
+    process.stderr.write(`    ${i + 1}. ${s && s.model}  [${s && s.gateway}]${note}\n`);
   });
   process.stderr.write('\n');
 
   const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
 
   const answer = await new Promise(resolve => {
-    rl.question(`  Select a model (1-${models.length}) or press Enter to cancel: `, resolve);
+    rl.question(`  Select (1-${suggestions.length}) or Enter to cancel: `, resolve);
   });
   rl.close();
 
   const idx = parseInt(answer, 10) - 1;
-  if (isNaN(idx) || idx < 0 || idx >= models.length) {
+  if (isNaN(idx) || idx < 0 || idx >= suggestions.length) {
     throw new Error('Model selection cancelled.');
   }
 
-  const selected = models[idx];
-  const newModel = normalizeModelId(provider, selected.id);
-
-  let config = loadConfig();
-  if (!config) {
-    const fs = require('fs');
-    const configPath = getConfigPath();
-    if (fs.existsSync(configPath)) {
-      throw new Error(
-        `Cannot save model selection: config file at ${configPath} is malformed. ` +
-        'Fix it manually or run \'amicus setup\'.'
-      );
+  const chosen = suggestions[idx];
+  const newModel = chosen.model;
+
+  if (alias) {
+    let config = loadConfig();
+    if (!config) {
+      const fs = require('fs');
+      const configPath = getConfigPath();
+      if (fs.existsSync(configPath)) {
+        throw new Error(
+          `Cannot save model selection: config file at ${configPath} is malformed. ` +
+          'Fix it manually or run \'amicus setup\'.'
+        );
+      }
+      config = {};
+    }
+    if (!config.aliases) { config.aliases = {}; }
+    config.aliases[alias] = newModel;
+    try {
+      saveConfig(config);
+      process.stderr.write(`  Saved: ${alias} -> ${newModel}\n`);
+    } catch (err) {
+      process.stderr.write(`  Warning: Could not save selection (${err.message}). Using for this session only.\n`);
     }
-    config = {};
-  }
-  if (!config.aliases) { config.aliases = {}; }
-  config.aliases[alias] = newModel;
-  try {
-    saveConfig(config);
-    process.stderr.write(`  Saved: ${alias} → ${newModel}\n`);
-  } catch (err) {
-    process.stderr.write(`  Warning: Could not save selection (${err.message}). Using for this session only.\n`);
   }
-  process.stderr.write(`  (To change later: amicus setup --add-alias ${alias}=...)\n\n`);
+  process.stderr.write('\n');
 
-  return newModel;
+  return { model: newModel, gateway: chosen.gateway };
 }
 
 /**
@@ -204,4 +182,10 @@ async function warnIfNotInCatalog(model) {
   }
 }
 
-module.exports = { validateDirectModel, filterRelevantModels, normalizeModelId, validateAgainstCatalog, warnIfNotInCatalog };
+module.exports = {
+  filterRelevantModels,
+  normalizeModelId,
+  validateAgainstCatalog,
+  warnIfNotInCatalog,
+  promptRouteSelection,
+};