amicus 2.2.0 → 3.1.0

package/src/utils/route-launch.js

@@ -0,0 +1,179 @@
+/**
+ * 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.
+ */
+'use strict';
+
+const { readApiKeys } = require('./api-key-store');
+const { readAuthJsonKeys } = require('./auth-json');
+const { KNOWN_PROVIDERS } = require('./provider-registry');
+
+/**
+ * Per-provider key presence across BOTH sources: env/.env (readApiKeys) and
+ * OpenCode's auth.json (readAuthJsonKeys). True if either source has a key
+ * for that provider (Foundation carry-forward, Decision 5).
+ * @returns {Object<string,boolean>} map of provider id -> key present
+ */
+function buildLaunchKeys() {
+  const env = readApiKeys(); // {openrouter:bool, google:bool, openai:bool, anthropic:bool, deepseek:bool}
+  const authKeys = readAuthJsonKeys(); // {provider:string,...} (only providers with keys)
+  const out = {};
+  for (const p of KNOWN_PROVIDERS) {
+    out[p] = !!env[p] || !!authKeys[p];
+  }
+  return out;
+}
+
+/**
+ * Thin wrapper over model-catalog.getCatalogInfo() for route-resolution
+ * callers that only need the models list and the last-refresh error, not the
+ * full cache metadata. Never throws: a catalog error resolves to an empty
+ * list with a sentinel error string.
+ * @returns {Promise<{models: Array, lastRefreshError: string|null}>}
+ */
+async function getRouteCatalogInfo() {
+  // Lazy-required so jest.doMock('./model-catalog', ...) can intercept it
+  // per-test, matching the pattern model-catalog.js itself uses for its deps.
+  const { getCatalogInfo } = require('./model-catalog');
+  try {
+    const info = await getCatalogInfo();
+    return { models: info.models || [], lastRefreshError: info.lastRefreshError || null };
+  } catch {
+    return { models: [], lastRefreshError: 'catalog-unavailable' };
+  }
+}
+
+/** 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 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).
+ *  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
+ * @returns {Array<{model:string, gateway:string, note:string}>}
+ */
+function buildSuggestions(descriptor, keys, catalogInfo) {
+  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 = `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
+ * silent). Advisory only — never changes the routing decision, and a failed
+ * persist (markMigrationNotified is itself best-effort) never blocks the
+ * launch. Fires only when ALL of these hold:
+ *  - the result actually resolved to gateway 'direct'
+ *  - the caller did NOT explicitly force a gateway (gatewayMode === 'auto');
+ *    an explicit --gateway direct means the user chose direct, no notice
+ *  - the descriptor is not itself an explicit `openrouter/...` literal
+ *  - the user holds an OpenRouter key (otherwise nothing is being migrated
+ *    FROM)
+ *  - this vendor hasn't already been notified (getRoutingConfig().migration_notified)
+ * @param {{result:object, descriptor:object, gatewayMode:string, keys:object}} args
+ * @returns {object} the (possibly mutated) result
+ */
+function maybeMigrationNotice({ result, descriptor, gatewayMode, keys }) {
+  if (result.kind !== 'resolved' || result.gateway !== 'direct') { return result; }
+  if (gatewayMode !== 'auto') { return result; }
+  if (descriptor.isExplicitOpenRouter) { return result; }
+  if (!keys.openrouter) { return result; }
+  try {
+    // Lazy-required so jest.doMock('./config', ...) can intercept it per-test.
+    const { getRoutingConfig, markMigrationNotified } = require('./config');
+    if (getRoutingConfig().migration_notified[descriptor.vendor]) { return result; }
+    const notice = `Routing ${descriptor.vendor} via direct API (previously OpenRouter). ` +
+      'Set routing.prefer: "openrouter" (or use --gateway openrouter) to restore.';
+    result.notice = result.notice ? `${result.notice} ${notice}` : notice;
+    markMigrationNotified(descriptor.vendor);
+  } catch (_err) {
+    // Advisory only: never let a lookup/persist failure change the routing
+    // decision or block the launch.
+  }
+  return result;
+}
+
+/**
+ * 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.
+ * @param {{model:string, gatewayMode:string, source:string, allowSelection?:boolean, validateModel?:boolean}} opts
+ * @returns {Promise<object>} RouteResult (resolved | selection_required | error)
+ */
+async function resolveRouteForLaunch({ model, gatewayMode, source, allowSelection, validateModel }) {
+  // Lazy-required so jest.doMock('./config' | './model-descriptor' | './gateway-router', ...)
+  // can intercept them per-test, matching the pattern already used above for model-catalog.
+  const { getEffectiveAliases } = require('./config');
+  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 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.
+  const catalogInfo = validateModel === false ? { models: [], lastRefreshError: null } : await getRouteCatalogInfo();
+  let result = resolveRoute({ descriptor, source, gatewayMode, allowSelection, validateModel, keys, catalogInfo });
+  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);
+  }
+  return result;
+}
+
+module.exports = { buildLaunchKeys, getRouteCatalogInfo, resolveRouteForLaunch, buildSuggestions, ROUTE_VERSION };

package/src/utils/start-helpers.js

@@ -6,71 +6,124 @@
  */
 
 /**
- * Resolve model from args: resolve alias or config default.
- * Returns { model, alias } or calls process.exit(1) on error.
+ * Derive the alias used for resolution (needed downstream by the budget gate,
+ * which reports `alias || args.model` as the pricing lookup's modelInput).
+ * Per the #61 Task 4.5 design, only ever returns a no-slash token: an
+ * explicit `--model` containing '/' or a slash-bearing config default both
+ * resolve to undefined here.
  * @param {object} args - Parsed CLI arguments
- * @returns {{ model: string, alias: string|undefined }}
+ * @returns {string|undefined}
  */
-function resolveModelFromArgs(args) {
-  const { resolveModel, loadConfig } = require('./config');
-  const rawAlias = args.model;
-  let model;
-  try {
-    model = resolveModel(args.model);
-  } catch (err) {
-    console.error(err.message);
-    process.exit(1);
+function deriveAlias(args) {
+  const raw = args.model;
+  if (raw !== undefined && raw !== null && !raw.includes('/')) {
+    return raw;
   }
-
-  // Determine the alias used (explicit or config default)
-  let alias = rawAlias;
-  if (alias === undefined) {
+  if (raw === undefined || raw === null) {
+    const { loadConfig } = require('./config');
     const cfg = loadConfig();
     if (cfg && cfg.default && !cfg.default.includes('/')) {
-      alias = cfg.default;
+      return cfg.default;
     }
   }
-  return { model, alias };
+  return undefined;
 }
 
 /**
- * Validate models before launch (F3 #18: default-on).
- * --no-validate-model opts out; the old opt-in --validate-model is a no-op kept for back-compat.
- * Returns the (possibly corrected) model string.
+ * Resolve the model for a launch through the Foundation gateway router (#61
+ * Task 4.5), used by every launch path — start, continue (Task 7.3), and the
+ * MCP amicus_start handler (via the same router, Task 6.2). This replaced the
+ * legacy resolveModelFromArgs + validateFallbackModel pair, which was retired
+ * once no launch path depended on it (#61 Task 4.7).
+ *
+ * On `resolved`, returns `{ model, alias, gateway, provenance }` (and prints
+ * any advisory `notice` to stderr). On `error` or `selection_required`,
+ * renders the appropriate message to stderr and exits(1) — this never
+ * returns in that case.
  * @param {object} args - Parsed CLI arguments
- * @param {string|undefined} alias - The alias used for resolution
- * @returns {Promise<string>} Validated model string
+ * @returns {Promise<{model: string, alias: string|undefined, gateway: string, provenance: object}>}
  */
-async function validateFallbackModel(args, alias) {
-  // F3 #18: validation is default-on. --no-validate-model opts out; the old
-  // opt-in --validate-model is now a no-op kept for back-compat.
-  if (args['no-validate-model']) { return args.model; }
+async function resolveLaunchModel(args) {
+  const { resolveGatewayMode } = require('./config');
+  const { resolveRouteForLaunch } = require('./route-launch');
+  const { toCliMessage, toStructuredError } = require('./route-error');
+  const { resolveModelInputOrDefault } = require('./model-input-default');
 
-  const headless = args['no-ui'] || !process.stdin.isTTY;
-  const { detectFallback } = require('./config');
+  const gatewayMode = resolveGatewayMode(args.gateway);
+  const validateModel = !args['no-validate-model'];
+  // Interactive alternatives picker (#61 Task 6.3): only offered on a real
+  // interactive TTY session that hasn't opted out with --no-ui. A headless/
+  // non-TTY run (CI, piped output, --no-ui) keeps allowSelection false, so a
+  // direct miss there still produces the structured error/selection_required
+  // rendered below rather than an unhandled prompt.
+  const allowSelection = !args['no-ui'] && !!process.stdin.isTTY;
+
+  // No --model given: the parser does not inject a default, so resolve the
+  // configured default here before handing off to the router. Without this, `undefined`
+  // would reach resolveRouteForLaunch -> parseDescriptor(undefined) -> an
+  // `invalid` result, breaking the common `amicus start` (no --model) case.
+  // Shared with the MCP amicus_start handler (mcp-server.js, #61 Task 6.2)
+  // via model-input-default.js, so this lookup lives in exactly one place.
+  const modelInput = resolveModelInputOrDefault(args.model);
+  if (modelInput === undefined) {
+    process.stderr.write(
+      'No model specified and no default configured. Run \'amicus setup\' to set a default model.\n'
+    );
+    process.exit(1);
+  }
 
-  // Direct-API fallback path: keep the provider-API existence check.
-  if (alias && detectFallback(alias, args.model)) {
-    const { validateDirectModel } = require('./model-validator');
+  const result = await resolveRouteForLaunch({
+    model: modelInput,
+    gatewayMode,
+    source: 'cli',
+    allowSelection,
+    validateModel,
+  });
+
+  if (result.kind === 'resolved') {
+    if (result.notice) {
+      process.stderr.write(`${result.notice}\n`);
+    }
+    return {
+      model: result.executableId,
+      alias: deriveAlias(args),
+      gateway: result.gateway,
+      provenance: result.provenance,
+    };
+  }
+
+  // Interactive alternatives picker (#61 Task 6.3): only reachable when
+  // allowSelection was true above (real TTY, no --no-ui), so the router only
+  // ever hands back selection_required here in that same interactive case.
+  if (result.kind === 'selection_required') {
+    const { promptRouteSelection } = require('./model-validator');
     try {
-      return await validateDirectModel(args.model, alias, { headless });
+      const chosen = await promptRouteSelection(result, deriveAlias(args));
+      return {
+        model: chosen.model,
+        alias: deriveAlias(args),
+        gateway: chosen.gateway,
+        provenance: result.provenance || {},
+      };
     } catch (err) {
-      console.error(err.message);
+      process.stderr.write(`${err.message || 'Model selection cancelled.'}\n`);
       process.exit(1);
     }
   }
 
-  // OpenRouter (and any) resolved model: validate against the live catalog.
-  const { validateAgainstCatalog } = require('./model-validator');
-  try {
-    return await validateAgainstCatalog(args.model, alias);
-  } catch (err) {
-    console.error(err.message);
-    process.exit(1);
+  // 'error': render and exit. (A non-interactive run never reaches
+  // kind:'selection_required' — allowSelection is false there, so the router
+  // resolves a catalog miss straight to kind:'error' with reason
+  // 'model_not_found' instead; see gateway-router.js's catalogGate.)
+  if (args.json) {
+    process.stderr.write(`${JSON.stringify(toStructuredError(result))}\n`);
+  } else {
+    process.stderr.write(`${toCliMessage(result)}\n`);
   }
+  process.exit(1);
 }
 
 module.exports = {
-  resolveModelFromArgs,
-  validateFallbackModel,
+  resolveLaunchModel,
+  deriveAlias,
 };

package/src/utils/validators.js

@@ -19,13 +19,7 @@ const VALID_AGENT_MODES = OPENCODE_AGENTS;
 /**
  * Provider to API key mapping
  */
-const PROVIDER_KEY_MAP = {
-  'openrouter': { key: 'OPENROUTER_API_KEY', name: 'OpenRouter' },
-  'google': { key: 'GOOGLE_GENERATIVE_AI_API_KEY', name: 'Google Gemini' },
-  'openai': { key: 'OPENAI_API_KEY', name: 'OpenAI' },
-  'anthropic': { key: 'ANTHROPIC_API_KEY', name: 'Anthropic' },
-  'deepseek': { key: 'DEEPSEEK_API_KEY', name: 'DeepSeek' },
-};
+const { PROVIDER_KEY_MAP } = require('./provider-registry');
 
 /** Task ID format: alphanumeric, hyphens, underscores, 1-64 chars */
 const TASK_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
@@ -272,5 +266,4 @@ module.exports = {
   findSessionInProjectDirs,
   // Re-exported from input-validators.js
   validateStartInputs: require('./input-validators').validateStartInputs,
-  findSimilar: require('./input-validators').findSimilar,
 };