amicus 3.0.0 → 3.1.1

package/src/utils/result-schema.js

@@ -121,9 +121,10 @@ function waveExitCode(waveStatus) {
  * @param {string|null} [opts.createdAt]
  * @param {string|null} [opts.completedAt]
  * @param {string|null} [opts.status] - Override (e.g. 'aborted' on signal); default aggregates legs
+ * @param {string[]} [opts.notices] - Advisory per-leg migration notices (#61 FIX 2); never affects status/exitCode.
  * @returns {object} wave document
  */
-function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null }) {
+function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [] }) {
   const { sumWaveUsage } = require('./pricing');
   // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
   // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
@@ -149,84 +150,13 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
     completedAt,
     durationMs,
     usage: sumWaveUsage(legs),
+    notices: Array.isArray(notices) ? notices.filter(Boolean) : [],
   };
 }
 
-/**
- * Rebuild a run document from a persisted session directory.
- * @param {string} project - Project dir
- * @param {string} taskId
- * @returns {object} run document
- * @throws {Error} if the session does not exist or metadata.json is missing/corrupt
- */
-function buildRunResultFromSession(project, taskId) {
-  const fs = require('fs');
-  const path = require('path');
-  const { resolveExistingSessionDir } = require('../session-manager');
-  const sessionDir = resolveExistingSessionDir(project, taskId);
-  const metaPath = path.join(sessionDir, 'metadata.json');
-  if (!fs.existsSync(metaPath)) {
-    throw new Error(`Session ${taskId} not found`);
-  }
-  let metadata;
-  try {
-    metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-  } catch (err) {
-    throw new Error(`Session ${taskId}: metadata is corrupt (${err.message})`);
-  }
-  const summaryPath = path.join(sessionDir, 'summary.md');
-  const summary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf-8') : null;
-  return buildRunResult({ taskId, metadata, summary, sessionDir });
-}
-
-/**
- * Rebuild a wave document. Prefers the stored wave.json (written atomically at
- * fanout exit); falls back to a live rebuild from leg sessions (e.g. after a
- * hard kill of the fanout process).
- * @param {string} project
- * @param {string} waveId
- * @returns {object} wave document
- * @throws {Error} if the wave session does not exist or metadata.json is missing/corrupt
- */
-function buildWaveResultFromSession(project, waveId) {
-  const fs = require('fs');
-  const path = require('path');
-  const { resolveExistingSessionDir } = require('../session-manager');
-  const waveDir = resolveExistingSessionDir(project, waveId);
-  const wavePath = path.join(waveDir, 'wave.json');
-  if (fs.existsSync(wavePath)) {
-    try {
-      return JSON.parse(fs.readFileSync(wavePath, 'utf-8'));
-    } catch {
-      // Corrupt wave.json (e.g. hard-kill mid-write) — fall through to live rebuild
-    }
-  }
-  const metaPath = path.join(waveDir, 'metadata.json');
-  if (!fs.existsSync(metaPath)) {
-    throw new Error(`Wave ${waveId} not found`);
-  }
-  let meta;
-  try {
-    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-  } catch (err) {
-    throw new Error(`Wave ${waveId}: metadata is corrupt (${err.message})`);
-  }
-  const legs = (meta.legs || []).map((legId) => {
-    try { return buildRunResultFromSession(project, legId); }
-    catch (err) {
-      const { logger } = require('./logger');
-      logger.warn('Failed to rebuild leg session; using unknown stub', { legId, error: err.message });
-      return buildRunResult({ taskId: legId, metadata: { status: 'unknown', parentWave: waveId } });
-    }
-  });
-  return buildWaveResult({
-    waveId,
-    legs,
-    promptMeta: meta.promptMeta || null,
-    createdAt: meta.createdAt || null,
-    completedAt: meta.completedAt || null,
-  });
-}
+// buildRunResultFromSession/buildWaveResultFromSession live in
+// ./result-schema-rebuild.js (size-gate split); re-exported below.
+const { buildRunResultFromSession, buildWaveResultFromSession } = require('./result-schema-rebuild');
 
 /**
  * Build a model-catalog document (`models [--search] [--refresh] --json`).
@@ -252,15 +182,22 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
 
 /**
  * Build an alias-audit document (`models --check --json`).
- * @param {{stale: Array<{alias,model,source,suggestions}>, catalogAvailable: boolean}} opts
+ * `gatewayFindings` (Task 6, #gwid) is additive: the per-gateway-form audit
+ * of curated DEFAULT aliases (toGatewayRoutes() vs. the live catalog),
+ * distinct from the flat `stale` audit above. Defaults to [] so existing
+ * callers that omit it are unaffected.
+ * @param {{stale: Array<{alias,model,source,suggestions}>, catalogAvailable: boolean,
+ *   gatewayFindings?: Array<{alias,gateway,kind,model,expected?}>}} opts
  */
-function buildAuditDoc({ stale, catalogAvailable }) {
+function buildAuditDoc({ stale, catalogAvailable, gatewayFindings = [] }) {
   return {
     schemaVersion: SCHEMA_VERSION,
     type: 'alias-audit',
     catalogAvailable,
     staleCount: stale.length,
     stale,
+    gatewayFindingsCount: gatewayFindings.length,
+    gatewayFindings,
   };
 }
 

package/src/utils/route-error.js

@@ -0,0 +1,154 @@
+/**
+ * @module route-error
+ * Shared renderer (#61 Task 6.1): turns a router RouteResult — an error or a
+ * selection_required — into the two surfaces that need to explain it:
+ *   - `toStructuredError` -> the MCP-facing structured object
+ *   - `toCliMessage`      -> a human stderr string for the CLI
+ *
+ * Pure module: no I/O, no requires of launch modules (cli.js/headless.js/
+ * mcp-server.js/etc). Wired into live launch paths — start-helpers.js,
+ * sidecar/fanout-leg.js, and mcp-server.js all render RouteResults through
+ * toStructuredError/toCliMessage.
+ *
+ * Router error shape (src/utils/model-descriptor.js `routeError()`):
+ *   {kind:'error', type:'model_route_error', field, requested, reason,
+ *    preferredGateway, suggestions}
+ * Selection shape (`selectionRequired()`):
+ *   {kind:'selection_required', requested, suggestions}
+ *
+ * The router's error `reason` is NOT limited to the 7 values in
+ * ROUTE_ERROR_REASONS below — that array is just the original/base set,
+ * intentionally pinned as-is (see its own doc comment). The router can also
+ * emit availability reasons (`direct_unavailable`, `openrouter_unavailable`),
+ * which have REASON_TEXT/FIX_HINTS entries but are deliberately excluded from
+ * ROUTE_ERROR_REASONS. A `selection_required` result has no `reason` of its
+ * own — it is synthesized here as SELECTION_REQUIRED_REASON, kept in the same
+ * documented REASON_TEXT map rather than invented ad hoc, so callers can
+ * treat every rendered structured error the same way regardless of which
+ * RouteResult produced it.
+ */
+'use strict';
+
+/**
+ * The original/base set of router error reasons — NOT an exhaustive list of
+ * every reason a router error can carry. Pinned to exactly these 7 values by
+ * a back-compat test (route-error.test.js:14-24), so this array must not be
+ * extended when new reasons are added. The router also emits
+ * `direct_unavailable` and `openrouter_unavailable` (REASON_TEXT/FIX_HINTS
+ * below have entries for both); those are intentionally left out of this
+ * array. Do not use ROUTE_ERROR_REASONS as an exhaustive switch/allow-list.
+ */
+const ROUTE_ERROR_REASONS = Object.freeze([
+  'gateway_conflict',
+  'no_openrouter_key',
+  'no_direct_integration',
+  'no_direct_key',
+  'no_key_for_vendor',
+  'model_not_found',
+  'invalid_descriptor',
+]);
+
+/**
+ * Synthesized reason for a `selection_required` RouteResult. Deliberately
+ * distinct from 'model_not_found': the model wasn't missing, it was ambiguous
+ * (multiple catalog candidates) and the router is asking the caller to pick.
+ */
+const SELECTION_REQUIRED_REASON = 'selection_required';
+
+/** One-line, non-technical explanation of what went wrong, keyed by reason. */
+const REASON_TEXT = Object.freeze({
+  gateway_conflict: 'This model must go through OpenRouter, but --gateway direct was forced.',
+  no_openrouter_key: 'No OpenRouter API key is configured.',
+  no_direct_integration: 'This vendor has no direct API integration.',
+  no_direct_key: "No API key is configured for this vendor's direct API.",
+  no_key_for_vendor: 'No API key was found for this vendor via any gateway.',
+  model_not_found: 'The requested model was not found in the catalog.',
+  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.",
+  [SELECTION_REQUIRED_REASON]: 'Multiple models match your request; a specific one must be selected.',
+});
+
+/** Copy-paste fix guidance appended after the REASON_TEXT sentence. */
+const FIX_HINTS = Object.freeze({
+  gateway_conflict: "An openrouter/... model can't be forced with --gateway direct.",
+  no_openrouter_key: 'Set OPENROUTER_API_KEY, or use --gateway direct.',
+  no_direct_integration: 'This vendor has no direct integration; drop --gateway direct.',
+  no_direct_key: 'Add a key with `amicus key <vendor> <key>`, or use --gateway openrouter.',
+  no_key_for_vendor: 'Add a provider key or an OpenRouter key.',
+  model_not_found: 'Run `amicus models --refresh`, or pass --no-validate-model.',
+  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.',
+  [SELECTION_REQUIRED_REASON]: 'Pick one of the suggestions below, or narrow the model id.',
+});
+
+/** @returns {Array} suggestions normalized to an array. */
+function normalizeSuggestions(suggestions) {
+  return Array.isArray(suggestions) ? suggestions : [];
+}
+
+/**
+ * Render a router RouteResult (error or selection_required) into the
+ * MCP-facing structured object. Pass-through/normalize for an `error` result;
+ * synthesized for a `selection_required` result.
+ * @param {object} result a RouteResult with kind 'error' or 'selection_required'
+ * @returns {{type:'model_route_error', field:string, requested:*, reason:string,
+ *   preferredGateway:(string|null), suggestions:Array}}
+ */
+function toStructuredError(result) {
+  const r = result || {};
+  if (r.kind === 'selection_required') {
+    return {
+      type: 'model_route_error',
+      field: 'model',
+      requested: r.requested,
+      reason: SELECTION_REQUIRED_REASON,
+      preferredGateway: null,
+      suggestions: normalizeSuggestions(r.suggestions),
+    };
+  }
+  // Router `error` result (kind:'error'): pass through/normalize.
+  return {
+    type: 'model_route_error',
+    field: r.field || 'model',
+    requested: r.requested,
+    reason: r.reason,
+    preferredGateway: r.preferredGateway || null,
+    suggestions: normalizeSuggestions(r.suggestions),
+  };
+}
+
+/**
+ * Render a router RouteResult into a human stderr message: the reason's
+ * one-line explanation, an optional "Did you mean" suggestion list, and a
+ * fix hint.
+ * @param {object} result a RouteResult with kind 'error' or 'selection_required'
+ * @returns {string}
+ */
+function toCliMessage(result) {
+  const err = toStructuredError(result);
+  const sentence = REASON_TEXT[err.reason] || `Model routing error (${err.reason}).`;
+  const lines = [err.requested ? `${sentence} (requested "${err.requested}")` : sentence];
+
+  if (err.suggestions.length > 0) {
+    lines.push('Did you mean:');
+    for (const s of err.suggestions) {
+      const note = s && s.note ? ` — ${s.note}` : '';
+      lines.push(`  - ${s && s.model} (${s && s.gateway})${note}`);
+    }
+  }
+
+  const hint = FIX_HINTS[err.reason];
+  if (hint) { lines.push(hint); }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  toStructuredError,
+  toCliMessage,
+  REASON_TEXT,
+  ROUTE_ERROR_REASONS,
+  SELECTION_REQUIRED_REASON,
+};

package/src/utils/route-launch.js

@@ -0,0 +1,219 @@
+/**
+ * Route-launch views (#61 gateway routing integration, Task 4.2).
+ *
+ * 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';
+
+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/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
+ * 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; gatewayIds bridging
+ * Task 3 of #61's gateway-correct-model-ids fix).
+ * 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.
+ *
+ * When the alias is UNMODIFIED from its curated default (effective value ===
+ * getDefaultAliases()[alias]), this also looks up curated-models'
+ * toGatewayRoutes()[alias] and threads it through as `gatewayIds`, and parses
+ * the descriptor from the gateway-native direct form (falling back to the
+ * openrouter form) rather than the single pinned alias string — the pinned
+ * string can be the wrong per-gateway form for divergent vendors (e.g.
+ * Anthropic's dash ids vs. OpenRouter's dot ids), so `toGatewayRoutes()` is
+ * the source of truth for actually-correct ids. A USER OVERRIDE (the
+ * effective alias differs from the curated default) or an alias with no
+ * curated route map intentionally skips all of this: no gatewayIds, and the
+ * user's own alias string is parsed as before — we must never impose curated
+ * Anthropic-style ids onto a target the user chose themselves. Full-id /
+ * non-alias inputs are likewise unaffected (no gatewayIds).
+ *
+ * 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)
+ */
+async function resolveRouteForLaunch({ model, gatewayMode, source, allowSelection, validateModel }) {
+  // Lazy-required so jest.doMock('./config' | './model-descriptor' | './gateway-router' | './curated-models', ...)
+  // can intercept them per-test, matching the pattern already used above for model-catalog.
+  const { getEffectiveAliases, getDefaultAliases } = require('./config');
+  const { parseDescriptor } = require('./model-descriptor');
+  const { resolveRoute } = require('./gateway-router');
+  const { toGatewayRoutes } = require('./curated-models');
+  const aliases = getEffectiveAliases();
+  const isAlias = typeof model === 'string' && !model.includes('/') && !!aliases[model];
+  let concrete = isAlias ? aliases[model] : model;
+  let gatewayIds;
+  if (isAlias && aliases[model] === getDefaultAliases()[model]) {
+    const routes = toGatewayRoutes()[model];
+    if (routes) {
+      gatewayIds = routes;
+      concrete = routes.direct || routes.openrouter;
+    }
+  }
+  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, 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, gatewayIds);
+  }
+  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,
 };