amicus 2.2.0 → 3.1.0

package/src/utils/config.js

@@ -8,7 +8,8 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { applyDirectApiFallback, autoRepairAlias } = require('./alias-resolver');
+const { autoRepairAlias } = require('./alias-resolver');
+const { isDirectProvider } = require('./provider-registry');
 
 /** Default model alias map — derived from the curated-models single source (F5) */
 const { toDefaultAliases } = require('./curated-models');
@@ -111,7 +112,9 @@ function resolveModel(modelArg) {
       if (!resolved || resolved === 'null') {
         return autoRepairAlias(modelArg, config, DEFAULT_ALIASES, saveConfig);
       }
-      return applyDirectApiFallback(resolved);
+      // Router (route-launch.js / gateway-router.js, #61) owns the
+      // direct-vs-OpenRouter decision now — return the stored id verbatim.
+      return resolved;
     }
 
     // Unknown alias
@@ -140,7 +143,8 @@ function resolveModel(modelArg) {
     if (!resolved || resolved === 'null') {
       return autoRepairAlias(defaultValue, config, DEFAULT_ALIASES, saveConfig);
     }
-    return applyDirectApiFallback(resolved);
+    // Router owns the direct-vs-OpenRouter decision now — return verbatim.
+    return resolved;
   }
 
   // Default alias not found anywhere
@@ -235,16 +239,42 @@ function tryResolveModel(modelArg) {
   }
 }
 
-/** Build OpenCode provider.models config from sidecar aliases.
+/** Build OpenCode provider.models config from sidecar aliases, plus the
+ * actually-resolved launch route(s). The alias-derived entries let the UI
+ * model picker show every configured model (single source of truth for the
+ * picker); resolvedRoutes ensures the id OpenCode is ACTUALLY told to launch
+ * (config.model) is always registered under its correct provider, even when
+ * an alias maps to a different provider for the same model (e.g. an alias
+ * stores `openrouter/openai/gpt-5.5` but the router resolves DIRECT to
+ * `openai/gpt-5.5` — without this, only `openrouter` would be registered,
+ * mismatching config.model).
+ *
+ * Catalog broadening (#61 whole-branch review, FIX 1): a resolvedRoutes entry
+ * only covers the route(s) resolved AT SERVER-CREATION TIME. A long-lived,
+ * multi-session server (the MCP shared server, `utils/shared-server.js`) is
+ * created ONCE via `sharedServer.ensureServer()` and then serves MANY
+ * sessions over its lifetime, each of which independently asks the gateway
+ * router (direct-first policy) to route the SAME bare alias — some sessions
+ * land DIRECT, others land on OpenRouter, depending on which keys happen to
+ * be configured when each session starts. Since the shared server's
+ * `provider.models` is fixed at creation and never rebuilt per-session,
+ * threading only that first session's resolved id is insufficient. So for
+ * every alias that resolves to a BARE direct-capable-vendor id (post-#61
+ * default aliases are bare, e.g. `openai/gpt-5.5`), this ALSO registers the
+ * `openrouter/<vendor>/<model>` form — broadening the catalog to cover BOTH
+ * routes the router might pick, regardless of which session created the
+ * server. This does NOT change what the alias itself resolves to (still
+ * bare, still direct-first) — it only widens what's pre-registered.
+ * @param {string[]} [resolvedRoutes] executable model id(s) actually launched
  * @returns {object} e.g. { openrouter: { models: { "x-ai/grok-4.3": {}, ... } } } */
-function buildProviderModels() {
+function buildProviderModels(resolvedRoutes = []) {
   const aliases = getEffectiveAliases();
   const providers = {};
 
-  for (const fullModel of Object.values(aliases)) {
-    if (!fullModel || typeof fullModel !== 'string') { continue; }
+  const addRoute = (fullModel) => {
+    if (!fullModel || typeof fullModel !== 'string') { return; }
     const parts = fullModel.split('/');
-    if (parts.length < 2) { continue; }
+    if (parts.length < 2) { return; }
 
     const providerID = parts[0];
     const modelID = parts.slice(1).join('/');
@@ -253,16 +283,28 @@ function buildProviderModels() {
       providers[providerID] = { models: {} };
     }
     providers[providerID].models[modelID] = {};
+  };
+
+  for (const fullModel of Object.values(aliases)) {
+    addRoute(fullModel);
+
+    // Broaden: a bare direct-capable-vendor route also gets an OpenRouter
+    // mirror registered (see catalog-broadening note above). Gateway-only
+    // aliases (already `openrouter/...`, e.g. grok/qwen/x-ai) are untouched —
+    // OpenRouter is their only possible route anyway, already covered above.
+    if (typeof fullModel === 'string' && !fullModel.startsWith('openrouter/')) {
+      const vendor = fullModel.split('/')[0];
+      if (isDirectProvider(vendor)) {
+        addRoute(`openrouter/${fullModel}`);
+      }
+    }
   }
 
-  return providers;
-}
+  for (const resolved of resolvedRoutes) {
+    addRoute(resolved);
+  }
 
-/** Detect if direct API fallback was applied during alias resolution */
-function detectFallback(alias, resolvedModel) {
-  if (!alias || alias.includes('/')) { return false; }
-  const val = getEffectiveAliases()[alias];
-  return !!(val && val.startsWith('openrouter/') && !resolvedModel.startsWith('openrouter/'));
+  return providers;
 }
 
 /** @returns {Object<string,string[]>} the councils map (empty if none) */
@@ -339,6 +381,44 @@ function resolveCouncilMembers(name, catalog = []) {
   return { models, dropped };
 }
 
+/** @returns {{prefer:'direct'|'openrouter', migration_notified:Object}} routing config with defaults */
+function getRoutingConfig() {
+  const config = loadConfig() || {};
+  const r = (config.routing && typeof config.routing === 'object') ? config.routing : {};
+  const prefer = r.prefer === 'openrouter' ? 'openrouter' : 'direct';
+  const migration_notified = (r.migration_notified && typeof r.migration_notified === 'object') ? r.migration_notified : {};
+  return { prefer, migration_notified };
+}
+
+/** Merge --gateway (perCall) with routing.prefer into a router gatewayMode.
+ * @param {string|undefined} perCall 'auto'|'direct'|'openrouter'|undefined
+ * @returns {'auto'|'direct'|'openrouter'} */
+function resolveGatewayMode(perCall) {
+  if (perCall && perCall !== 'auto') { return perCall; }
+  const { prefer } = getRoutingConfig();
+  return prefer === 'openrouter' ? 'openrouter' : 'auto';
+}
+
+/**
+ * Persist the one-time direct-migration notice flag for a vendor (#61 Task
+ * 5.1 — visible-migration guarantee). Best-effort: swallows any saveConfig
+ * failure so a persistence hiccup never breaks the launch that triggered it.
+ * @param {string} vendor
+ */
+function markMigrationNotified(vendor) {
+  try {
+    const config = loadConfig() || {};
+    if (!config.routing || typeof config.routing !== 'object') { config.routing = {}; }
+    if (!config.routing.migration_notified || typeof config.routing.migration_notified !== 'object') {
+      config.routing.migration_notified = {};
+    }
+    config.routing.migration_notified[vendor] = true;
+    saveConfig(config);
+  } catch (_err) {
+    // best-effort: never fail the launch over a persistence error
+  }
+}
+
 module.exports = {
   getConfigDir,
   getConfigPath,
@@ -346,7 +426,6 @@ module.exports = {
   saveConfig,
   getDefaultAliases,
   resolveModel,
-  detectFallback,
   computeConfigHash,
   buildAliasTable,
   checkConfigChanged,
@@ -358,4 +437,7 @@ module.exports = {
   getCouncil,
   getCouncilWithSource,
   resolveCouncilMembers,
+  getRoutingConfig,
+  resolveGatewayMode,
+  markMigrationNotified,
 };

package/src/utils/curated-models.js

@@ -12,6 +12,8 @@
 
 'use strict';
 
+const { isDirectProvider } = require('./provider-registry');
+
 /**
  * Wizard quick-pick families. `idPattern` matches the model segment after
  * `<vendorPath>/` (openrouter ns) or `<provider>/` (direct ns).
@@ -91,15 +93,42 @@ function getFamilies() {
 }
 
 /**
- * @returns {Object<string,string>} alias → pinned route (openrouter first). STATIC — runtime-safe.
+ * Direct-first canonicalization for a pinned `openrouter/<vendor>/<rest>`
+ * route: when `<vendor>` has a direct integration (provider-registry
+ * `isDirectProvider`), strip the `openrouter/` prefix so the resulting bare
+ * `<vendor>/<rest>` id is policy-routed by the gateway router (direct when a
+ * direct key exists, OpenRouter otherwise). Gateway-only vendors (no direct
+ * integration — e.g. qwen, x-ai, z-ai, mistralai, minimax, moonshotai,
+ * bytedance-seed) are returned unchanged, since OpenRouter is their only
+ * route anyway. Non-openrouter routes (already bare, or malformed) pass
+ * through unchanged.
+ * @param {string} route
+ * @returns {string}
+ */
+function toCanonicalDefault(route) {
+  if (typeof route === 'string' && route.startsWith('openrouter/')) {
+    const rest = route.slice('openrouter/'.length); // '<vendor>/<rest...>'
+    const slashIdx = rest.indexOf('/');
+    const vendor = slashIdx > 0 ? rest.slice(0, slashIdx) : null;
+    if (vendor && isDirectProvider(vendor)) { return rest; }
+  }
+  return route;
+}
+
+/**
+ * @returns {Object<string,string>} alias → pinned route, direct-first for
+ * direct-capable vendors (bare `vendor/model`), openrouter-prefixed for
+ * gateway-only vendors. STATIC — runtime-safe.
  */
 function toDefaultAliases() {
   const out = {};
   for (const f of FAMILIES) {
-    out[f.alias] = f.fallback.openrouter || Object.values(f.fallback)[0];
+    const route = f.fallback.openrouter || Object.values(f.fallback)[0];
+    out[f.alias] = toCanonicalDefault(route);
   }
   for (const e of CARDLESS) {
-    out[e.alias] = e.routes.openrouter || Object.values(e.routes)[0];
+    const route = e.routes.openrouter || Object.values(e.routes)[0];
+    out[e.alias] = toCanonicalDefault(route);
   }
   return out;
 }
@@ -122,4 +151,4 @@ function listCuratedRoutes() {
   return out;
 }
 
-module.exports = { getFamilies, toDefaultAliases, listCuratedRoutes };
+module.exports = { getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes };

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);