amicus 3.1.0 → 3.2.0

package/src/utils/route-launch.js

@@ -1,9 +1,10 @@
 /**
  * Route-launch views (#61 gateway routing integration, Task 4.2).
  *
- * Additive, read-only helpers consumed by Task 4.4's resolveRouteForLaunch
- * (not wired into any launch path yet). Pure-ish: all I/O goes through the
- * stubbable api-key-store / auth-json / model-catalog modules.
+ * Read-only helpers consumed by resolveRouteForLaunch, which IS wired into
+ * live launch paths (start-helpers.js, mcp-server.js, sidecar/fanout-validate.js).
+ * Pure-ish: all I/O goes through the stubbable api-key-store / auth-json /
+ * model-catalog modules.
  */
 'use strict';
 
@@ -52,12 +53,20 @@ 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 the caller already assembled.
+ * 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 (`openrouter/<vendor>/<model>`) is actually
- *     present in the catalog (never suggest an id we can't confirm exists).
+ *     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
@@ -68,9 +77,13 @@ const ROUTE_VERSION = 1;
  *   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) {
+function buildSuggestions(descriptor, keys, catalogInfo, gatewayIds) {
   const suggestions = [];
   const vendor = descriptor && descriptor.vendor;
   const model = descriptor && descriptor.model;
@@ -80,7 +93,7 @@ function buildSuggestions(descriptor, keys, catalogInfo) {
   const requestedDirectId = `${vendor}/${model}`;
 
   if (keys && keys.openrouter) {
-    const orId = `openrouter/${vendor}/${model}`;
+    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' });
     }
@@ -137,14 +150,110 @@ function maybeMigrationNotice({ result, descriptor, gatewayMode, keys }) {
 }
 
 /**
- * Bridge: alias -> descriptor -> resolveRoute (Task 4.4).
- * Resolves a raw model string to a Descriptor — if it is a known no-slash
- * alias (per getEffectiveAliases()), its concrete id is parsed instead, so an
- * alias pointing at an `openrouter/...` value is treated as an explicit,
- * force-OR literal while an alias pointing at a bare `vendor/model` is
- * policy-routed like any other canonical id. Assembles live key/catalog state
- * and delegates the actual decision to the pure gateway-router. Additive:
- * not wired into any launch path yet.
+ * Comparison-only key for a gateway-native id: strip a leading `openrouter/`
+ * prefix, lowercase, unify dot/dash separators. Lets a divergent vendor's
+ * dash-form direct id, dot-form OpenRouter id, and a stale/reformatted
+ * variant (e.g. toDefaultAliases()'s dotted default) collapse to one key
+ * when they name the same model. Never used to construct/emit an id.
+ * @param {string} id @returns {string|null}
+ */
+function normalizeForModelIndex(id) {
+  if (typeof id !== 'string' || !id) { return null; }
+  const rest = id.startsWith('openrouter/') ? id.slice('openrouter/'.length) : id;
+  return rest.toLowerCase().replace(/\./g, '-');
+}
+
+/**
+ * By-model index of every curated route pair (Task 3 Part 2 / spec D2): each
+ * `{direct?, openrouter}` pair from toGatewayRoutes() is indexed under the
+ * normalized form of BOTH its values, so a lookup BY RESOLVED MODEL (not
+ * alias name) finds the pair regardless of which alias produced it or which
+ * gateway-native form the caller's id is in.
+ * @returns {Object<string,{direct?:string, openrouter?:string}>}
+ */
+function buildGatewayRoutesByModel() {
+  const { toGatewayRoutes } = require('./curated-models');
+  const byModel = {};
+  for (const pair of Object.values(toGatewayRoutes())) {
+    const directKey = normalizeForModelIndex(pair.direct);
+    const orKey = normalizeForModelIndex(pair.openrouter);
+    if (directKey) { byModel[directKey] = pair; }
+    if (orKey) { byModel[orKey] = pair; }
+  }
+  return byModel;
+}
+
+/**
+ * @param {string} resolvedId direct (`vendor/model`) or OR-prefixed
+ *   (`openrouter/vendor/model`) gateway-native id
+ * @returns {{vendor:string, bareModel:string}|null}
+ */
+function splitVendorAndModel(resolvedId) {
+  if (typeof resolvedId !== 'string') { return null; }
+  const rest = resolvedId.startsWith('openrouter/') ? resolvedId.slice('openrouter/'.length) : resolvedId;
+  const idx = rest.indexOf('/');
+  if (idx <= 0 || idx === rest.length - 1) { return null; }
+  return { vendor: rest.slice(0, idx), bareModel: rest.slice(idx + 1) };
+}
+
+/**
+ * Resolve `{direct?, openrouter?}` for `resolvedId`, for ANY alias — curated
+ * default, user override, or vendor alias (Task 3 Part 2 / spec D2; retires
+ * Part 1's curated-default-NAME-only guard). Two-step:
+ *  1. By-model curated lookup (buildGatewayRoutesByModel()) — covers curated
+ *     defaults byte-identically to Part 1, plus any alias resolving to the
+ *     same underlying curated model.
+ *  2. Catalog pairing fallback: for a DIVERGENT vendor not covered by (1),
+ *     ask the live catalog (gateway-route-catalog's pairAcrossGateways,
+ *     Task 5) to pair the two forms. Non-divergent vendors skip this — their
+ *     ids already match across gateways, so `executableFor`'s fallback is
+ *     already correct with no gatewayIds.
+ * FAIL-OPEN: any miss/malformed-input/thrown-error resolves to `undefined`
+ * (no gatewayIds) — never raises, never blocks a launch.
+ * @param {string} resolvedId @param {{models: Array}} catalogInfo
+ * @returns {{direct?:string, openrouter?:string}|undefined}
+ */
+function resolveGatewayIdsByModel(resolvedId, catalogInfo) {
+  try {
+    const key = normalizeForModelIndex(resolvedId);
+    const byModel = key ? buildGatewayRoutesByModel() : null;
+    if (byModel && byModel[key]) { return byModel[key]; }
+
+    const split = splitVendorAndModel(resolvedId);
+    if (!split) { return undefined; }
+    const { DIVERGENT_VENDORS } = require('./curated-models');
+    if (!DIVERGENT_VENDORS.has(split.vendor)) { return undefined; }
+
+    const { pairAcrossGateways } = require('./gateway-route-catalog');
+    const paired = pairAcrossGateways(split.vendor, split.bareModel, catalogInfo);
+    return (paired && (paired.direct || paired.openrouter)) ? paired : undefined;
+  } catch (_err) {
+    return undefined; // fail-open: a lookup error must never block the launch.
+  }
+}
+
+/**
+ * Bridge: alias -> descriptor -> resolveRoute (Task 4.4; gatewayIds bridging
+ * Task 3, generalized by-model in Part 2 Task 3 / spec D2).
+ * Resolves a raw model string to a Descriptor — a known no-slash alias (per
+ * getEffectiveAliases()) has its concrete id parsed instead, so an alias
+ * pointing at an `openrouter/...` value is an explicit force-OR literal
+ * while one pointing at a bare `vendor/model` is policy-routed normally.
+ *
+ * For ANY alias, the resolved concrete id is looked up BY MODEL via
+ * resolveGatewayIdsByModel() and threaded through as `gatewayIds` — the
+ * descriptor is then re-parsed from the gateway-native form (not the raw
+ * alias string, which can be the wrong per-gateway form for a divergent
+ * vendor, e.g. Anthropic's dash vs. OpenRouter's dot ids). Preserves Part
+ * 1's force-OR contract: an alias whose ORIGINAL value is an explicit
+ * `openrouter/...` literal prefers `gatewayIds.openrouter` (else falls back
+ * to that original value); any other alias value prefers `gatewayIds.direct`
+ * (else `.openrouter`) as before. Uncovered models get no gatewayIds
+ * (fail-open); full-id/non-alias inputs are unaffected.
+ *
+ * Assembles live key/catalog state and delegates the actual decision to the
+ * pure gateway-router. Wired into start-helpers.js, mcp-server.js, and
+ * sidecar/fanout-validate.js.
  * @param {{model:string, gatewayMode:string, source:string, allowSelection?:boolean, validateModel?:boolean}} opts
  * @returns {Promise<object>} RouteResult (resolved | selection_required | error)
  */
@@ -155,23 +264,34 @@ async function resolveRouteForLaunch({ model, gatewayMode, source, allowSelectio
   const { parseDescriptor } = require('./model-descriptor');
   const { resolveRoute } = require('./gateway-router');
   const aliases = getEffectiveAliases();
-  const concrete = (typeof model === 'string' && !model.includes('/') && aliases[model]) ? aliases[model] : model;
-  const descriptor = parseDescriptor(concrete, { aliases });
+  const isAlias = typeof model === 'string' && !model.includes('/') && !!aliases[model];
+  let concrete = isAlias ? aliases[model] : model;
   const keys = buildLaunchKeys();
-  // Skip the catalog fetch entirely under --no-validate-model: gateway-router's
-  // catalogGate short-circuits to { ok:true } as soon as validateModel === false,
-  // never consulting catalogInfo, so fetching it here would be wasted
-  // latency/network (and can hit the network on a cold cache) for no benefit.
-  // Strict === false (not just falsy) so this stays in lockstep with catalogGate's
-  // own `=== false` guard: any other value (incl. an omitted flag) still fetches,
-  // so a caller can never skip the fetch while the gate still classifies against it.
+  // Skip the catalog fetch entirely under --no-validate-model (catalogGate
+  // short-circuits without consulting catalogInfo when validateModel===false,
+  // so fetching would be wasted network/latency). Moved up from after
+  // descriptor parsing because the catalog-pairing fallback below needs it;
+  // otherwise independent of the descriptor/alias, so no other effect.
   const catalogInfo = validateModel === false ? { models: [], lastRefreshError: null } : await getRouteCatalogInfo();
-  let result = resolveRoute({ descriptor, source, gatewayMode, allowSelection, validateModel, keys, catalogInfo });
+  let gatewayIds;
+  if (isAlias) {
+    const originalConcrete = concrete; // pre-gatewayIds alias value; may itself be an explicit `openrouter/...` literal
+    gatewayIds = resolveGatewayIdsByModel(concrete, catalogInfo);
+    if (gatewayIds) {
+      // Force-OR contract (Part 1): an explicit openrouter/... alias value
+      // stays on OpenRouter; only a bare vendor/model value prefers direct.
+      concrete = originalConcrete.startsWith('openrouter/')
+        ? (gatewayIds.openrouter || originalConcrete)
+        : (gatewayIds.direct || gatewayIds.openrouter);
+    }
+  }
+  const descriptor = parseDescriptor(concrete, { aliases });
+  let result = resolveRoute({ descriptor, source, gatewayMode, allowSelection, validateModel, keys, catalogInfo, gatewayIds });
   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);
+    result.suggestions = buildSuggestions(descriptor, keys, catalogInfo, gatewayIds);
   }
   return result;
 }

package/src/utils/start-helpers.js

@@ -123,7 +123,60 @@ async function resolveLaunchModel(args) {
   process.exit(1);
 }
 
+/**
+ * Existing-user one-time onboarding offer (Part 2, Task 9). Prints a single
+ * non-blocking notice line pointing configured-but-not-yet-onboarded users at
+ * the per-provider cost-aware default picker (`amicus key <provider>`, Task
+ * 6). This is a PRINTED LINE, never an interactive prompt -- it must never
+ * wait on stdin.
+ *
+ * Fires only when ALL of:
+ *  - the session is interactive (a real TTY, and not --json/--quiet)
+ *  - the user hasn't already seen this notice (`hasTierOnboarded()` false)
+ *  - at least one DIRECT provider (openai/anthropic/google/deepseek, via
+ *    `provider-registry.listDirectProviders`) has a key configured
+ *  - the user hasn't already used the picker (no vendor-named alias set --
+ *    no key of `config.aliases` matches a direct-provider id)
+ *
+ * The flag is only ever set when the notice actually printed. If any gate
+ * fails, this is a no-op AND the flag is left unset -- a user who later adds
+ * a direct key (or a non-interactive run that becomes interactive) can still
+ * see the notice once. Wrapped end-to-end in try/catch: a bug here must never
+ * break the command it's attached to.
+ * @param {object} [args] parsed CLI args (checked for --json/--quiet to gate interactivity)
+ */
+function maybeOfferProviderDefaults(args = {}) {
+  try {
+    const interactive = !!process.stdin.isTTY && !args.json && !args.quiet;
+    if (!interactive) { return; }
+
+    const { hasTierOnboarded, markTierOnboarded, loadConfig } = require('./config');
+    if (hasTierOnboarded()) { return; }
+
+    const { listDirectProviders } = require('./provider-registry');
+    const { readApiKeys } = require('./api-key-store');
+    const directProviders = listDirectProviders();
+    const apiKeys = readApiKeys();
+    const hasDirectKey = directProviders.some((p) => apiKeys[p]);
+    if (!hasDirectKey) { return; }
+
+    const config = loadConfig() || {};
+    const aliases = (config.aliases && typeof config.aliases === 'object') ? config.aliases : {};
+    const hasVendorAlias = directProviders.some((p) => Object.prototype.hasOwnProperty.call(aliases, p));
+    if (hasVendorAlias) { return; }
+
+    process.stdout.write(
+      'Tip: run `amicus key <provider>` to pick a cost-aware default model per provider ' +
+      '(avoids defaulting to the priciest flagship).\n'
+    );
+    markTierOnboarded();
+  } catch (_err) {
+    // best-effort: never break the command this is attached to
+  }
+}
+
 module.exports = {
   resolveLaunchModel,
   deriveAlias,
+  maybeOfferProviderDefaults,
 };