converse-mcp-server 3.7.0 → 4.0.0

package/src/services/summarizationService.js

@@ -9,20 +9,21 @@
 import { createLogger } from '../utils/logger.js';
 import { debugLog, debugError } from '../utils/console.js';
 
-import { mapModelToProvider } from '../utils/modelRouting.js';
+import { resolveModelSpec } from '../utils/modelRouting.js';
 
 const logger = createLogger('summarization');
 
-// Default fast models for summarization tasks (prioritize GPT-5-nano for speed)
-const FAST_MODELS = {
-  openai: 'gpt-5-nano', // Fastest GPT-5 model with minimal reasoning
-  google: 'flash',
-  xai: 'grok-4.5',
-  anthropic: 'claude-3-5-haiku-latest',
-  mistral: 'mistral-small-latest',
-  deepseek: 'deepseek-v4-flash',
-  openrouter: 'z-ai/glm-5.2',
-};
+// Fast models for summarization tasks, tried in order (GPT-5-nano first for
+// speed). Namespaced so each names exactly one provider.
+export const FAST_MODELS = [
+  'openai:gpt-5-nano',
+  'google:gemini-2.5-flash',
+  'xai:grok-4.5',
+  'anthropic:claude-haiku-4-5-20251001',
+  'mistral:mistral-small-2603',
+  'deepseek:deepseek-v4-flash',
+  'openrouter:z-ai/glm-5.2',
+];
 
 export class SummarizationService {
   constructor(providers, config) {
@@ -51,16 +52,12 @@ export class SummarizationService {
 
     try {
       // Select fast model if not specified
-      const selectedModel = model || this._selectFastModel();
-      const providerName = mapModelToProvider(selectedModel, this.providers);
-      const provider = this.providers[providerName];
-
-      if (!provider || !provider.isAvailable(this.config)) {
-        debugLog(
-          `Summarization: Provider ${providerName} not available for title generation`,
-        );
+      const selected = this._resolve(model || this._selectFastModel());
+      if (!selected) {
+        debugLog('Summarization: No available model for title generation');
         return this._fallbackTitle(prompt);
       }
+      const { provider, resolvedModel: selectedModel } = selected;
 
       // Create messages for title generation
       const messages = [
@@ -112,16 +109,12 @@ export class SummarizationService {
 
     try {
       // Select fast model if not specified
-      const selectedModel = model || this._selectFastModel();
-      const providerName = mapModelToProvider(selectedModel, this.providers);
-      const provider = this.providers[providerName];
-
-      if (!provider || !provider.isAvailable(this.config)) {
-        debugLog(
-          `Summarization: Provider ${providerName} not available for streaming summary`,
-        );
+      const selected = this._resolve(model || this._selectFastModel());
+      if (!selected) {
+        debugLog('Summarization: No available model for streaming summary');
         return this._fallbackStreamingSummary(content, currentFocus);
       }
+      const { provider, resolvedModel: selectedModel } = selected;
 
       // Create messages for streaming summary
       const messages = [
@@ -175,16 +168,12 @@ export class SummarizationService {
 
     try {
       // Select fast model if not specified
-      const selectedModel = model || this._selectFastModel();
-      const providerName = mapModelToProvider(selectedModel, this.providers);
-      const provider = this.providers[providerName];
-
-      if (!provider || !provider.isAvailable(this.config)) {
-        debugLog(
-          `Summarization: Provider ${providerName} not available for final summary`,
-        );
+      const selected = this._resolve(model || this._selectFastModel());
+      if (!selected) {
+        debugLog('Summarization: No available model for final summary');
         return this._fallbackFinalSummary(content);
       }
+      const { provider, resolvedModel: selectedModel } = selected;
 
       // Create messages for final summary
       const messages = [
@@ -221,6 +210,20 @@ export class SummarizationService {
     }
   }
 
+  /**
+   * Route a model spec to its first available provider.
+   * @private
+   * @returns {{ provider: object, providerName: string, resolvedModel: string }|null}
+   */
+  _resolve(spec) {
+    const resolution = resolveModelSpec(spec, this.providers, this.config);
+    if (resolution.status !== 'ok') {
+      debugLog(`Summarization: ${resolution.error}`);
+      return null;
+    }
+    return resolution;
+  }
+
   /**
    * Select the best available fast model
    * @private
@@ -228,14 +231,10 @@ export class SummarizationService {
   _selectFastModel() {
     // If a model is configured, try to use it first
     if (this.configuredModel) {
-      const providerName = mapModelToProvider(
-        this.configuredModel,
-        this.providers,
-      );
-      const provider = this.providers[providerName];
-      if (provider && provider.isAvailable(this.config)) {
+      const resolution = resolveModelSpec(this.configuredModel, this.providers, this.config);
+      if (resolution.status === 'ok') {
         debugLog(
-          `Summarization: Using configured model ${this.configuredModel} from ${providerName}`,
+          `Summarization: Using configured model ${this.configuredModel} from ${resolution.providerName}`,
         );
         return this.configuredModel;
       }
@@ -244,13 +243,10 @@ export class SummarizationService {
       );
     }
 
-    // Check which providers are available and return the first fast model
-    for (const [providerName, fastModel] of Object.entries(FAST_MODELS)) {
-      const provider = this.providers[providerName];
-      if (provider && provider.isAvailable(this.config)) {
-        debugLog(
-          `Summarization: Selected fast model ${fastModel} from ${providerName}`,
-        );
+    // Return the first fast model whose provider is available
+    for (const fastModel of FAST_MODELS) {
+      if (resolveModelSpec(fastModel, this.providers, this.config).status === 'ok') {
+        debugLog(`Summarization: Selected fast model ${fastModel}`);
         return fastModel;
       }
     }

package/src/tools/chat.js

@@ -29,9 +29,8 @@ import { SummarizationService } from '../services/summarizationService.js';
 import { exportConversation } from '../utils/conversationExporter.js';
 import { EFFORT_LADDER } from '../utils/reasoningEffort.js';
 import {
-  getDefaultModelForProvider,
-  getProviderUnavailableMessage,
-  getAvailableProviders,
+  getAutoCandidates,
+  getAutoModelSpecs,
   resolveModelSpec,
 } from '../utils/modelRouting.js';
 import {
@@ -857,24 +856,52 @@ function buildAsyncResult(pipeline, title, finalSummary) {
 // --- Model resolution helpers ------------------------------------------------
 
 /**
- * Build the full provider-priority candidate list for an "auto" spec (used for
- * chat-mode failover). Skips text-only providers when the request has images.
+ * Convert router candidates into the engine's call-plan candidate shape.
  */
-function buildAutoCandidates(providers, config, hasImages) {
-  return getAvailableProviders(providers, config, { hasImages }).map((name) => ({
-    name,
-    providerInstance: providers[name],
-    resolvedModel: getDefaultModelForProvider(name),
-    displayModel: 'auto',
+function toPlanCandidates(candidates, displayModel) {
+  return candidates.map((c) => ({
+    name: c.providerName,
+    providerInstance: c.provider,
+    resolvedModel: c.resolvedModel,
+    displayModel,
+    resolveOptions: c.options,
   }));
 }
 
+/**
+ * Resolve one explicit spec into a call plan, or a pre-failed entry carrying
+ * the router's error (unknown names include "did you mean" suggestions). A
+ * bare model name served by several providers yields a multi-candidate plan
+ * that fails over in provider priority order.
+ */
+function resolveExplicitPlan(spec, providers, config) {
+  const resolution = resolveModelSpec(spec, providers, config);
+  if (resolution.status !== 'ok') {
+    return {
+      preFailed: {
+        model: spec,
+        ...(resolution.providerName && { provider: resolution.providerName }),
+        error: resolution.error,
+      },
+    };
+  }
+  return {
+    plan: {
+      modelSpec: spec,
+      displayModel: spec,
+      threadKey: spec,
+      candidates: toPlanCandidates(resolution.candidates, spec),
+    },
+  };
+}
+
 /**
  * Resolve chat-mode call plans. Each "auto" spec (whether the list is exactly
  * ["auto"] or "auto" appears alongside explicit models) yields a plan with the
  * full provider-priority candidate list (failover); explicit models yield one
- * single-candidate plan each. Unavailable/unknown explicit models are returned
- * as pre-failed entries (surfaced as per-model failures).
+ * plan each, with failover candidates when a bare name is served by several
+ * providers. Unavailable/unknown explicit models are returned as pre-failed
+ * entries (surfaced as per-model failures).
  */
 function resolveChatCallPlans(models, providers, config, hasImages) {
   const callPlans = [];
@@ -882,7 +909,10 @@ function resolveChatCallPlans(models, providers, config, hasImages) {
 
   for (const spec of models) {
     if (String(spec).toLowerCase() === 'auto') {
-      const candidates = buildAutoCandidates(providers, config, hasImages);
+      const candidates = toPlanCandidates(
+        getAutoCandidates(providers, config, { hasImages }),
+        'auto',
+      );
       if (candidates.length === 0) {
         // A single ["auto"] with no providers is a hard error; an "auto" entry
         // in a multi-model list becomes a per-model failure instead.
@@ -909,28 +939,11 @@ function resolveChatCallPlans(models, providers, config, hasImages) {
       continue;
     }
 
-    const { providerName, provider, resolvedModel, status, options } = resolveModelSpec(spec, providers, config);
-    if (status === 'not_found') {
-      preFailed.push({
-        model: spec,
-        provider: providerName,
-        error: `Provider not found for model: ${spec}`,
-      });
-    } else if (status === 'unavailable') {
-      preFailed.push({
-        model: spec,
-        provider: providerName,
-        error: getProviderUnavailableMessage(providerName),
-      });
+    const { plan, preFailed: failed } = resolveExplicitPlan(spec, providers, config);
+    if (failed) {
+      preFailed.push(failed);
     } else {
-      callPlans.push({
-        modelSpec: spec,
-        displayModel: spec,
-        threadKey: spec,
-        candidates: [
-          { name: providerName, providerInstance: provider, resolvedModel, displayModel: spec, resolveOptions: options },
-        ],
-      });
+      callPlans.push(plan);
     }
   }
   return { callPlans, preFailed, error: null };
@@ -938,15 +951,15 @@ function resolveChatCallPlans(models, providers, config, hasImages) {
 
 /**
  * Resolve consensus-mode call plans. Single "auto" expands to the first 3
- * available providers' default models; each spec becomes a single-candidate plan.
+ * available providers' default models (as `namespace:model` specs); each spec
+ * becomes one plan.
  */
 function resolveConsensusCallPlans(models, providers, config, images) {
   const hasImages = Array.isArray(images) && images.length > 0;
 
   let modelsToProcess = models;
   if (models.length === 1 && String(models[0]).toLowerCase() === 'auto') {
-    const available = getAvailableProviders(providers, config, { hasImages, limit: 3 });
-    modelsToProcess = available.map((name) => getDefaultModelForProvider(name));
+    modelsToProcess = getAutoModelSpecs(providers, config, { hasImages, limit: 3 });
   }
 
   const resolved = [];
@@ -956,20 +969,11 @@ function resolveConsensusCallPlans(models, providers, config, images) {
       preFailed.push({ model: spec || 'unknown', error: 'Invalid model specification' });
       continue;
     }
-    const { providerName, provider, resolvedModel, status, options } = resolveModelSpec(spec, providers, config);
-    if (status === 'not_found') {
-      preFailed.push({ model: spec, provider: providerName, error: `Provider not found: ${providerName}` });
-    } else if (status === 'unavailable') {
-      preFailed.push({ model: spec, provider: providerName, error: getProviderUnavailableMessage(providerName) });
+    const { plan, preFailed: failed } = resolveExplicitPlan(spec, providers, config);
+    if (failed) {
+      preFailed.push(failed);
     } else {
-      resolved.push({
-        modelSpec: spec,
-        displayModel: spec,
-        threadKey: spec,
-        candidates: [
-          { name: providerName, providerInstance: provider, resolvedModel, displayModel: spec, resolveOptions: options },
-        ],
-      });
+      resolved.push(plan);
     }
   }
   return { resolved, preFailed };
@@ -1161,7 +1165,7 @@ chatTool.inputSchema = {
       items: { type: 'string' },
       minItems: 1,
       description:
-        'Models to use. Examples: ["auto"] (recommended), ["codex"], ["codex", "gemini", "claude"]. In mode "chat" each model answers independently; in "consensus" they refine after seeing each other; in "roundtable" they speak in the given ORDER, each seeing the transcript. Default: ["auto"].',
+        'Models to use. Examples: ["auto"] (recommended), ["codex"], ["codex", "gemini", "claude"], ["codex:astra"], ["gpt-6-astra"]. Forms: "provider" (its default model), "provider:model" (that provider only), or a bare "model" (served by the first configured provider that offers it, local CLI providers first, failing over to the next). Providers: codex, gemini (agy), claude, copilot, openai, google, xai, anthropic, mistral, deepseek, openrouter. Unknown names are rejected with suggestions. In mode "chat" each model answers independently; in "consensus" they refine after seeing each other; in "roundtable" they speak in the given ORDER, each seeing the transcript. Default: ["auto"].',
     },
     mode: {
       type: 'string',

package/src/tools/modes/roundtable.js

@@ -20,12 +20,8 @@
 
 import { debugLog } from '../../utils/console.js';
 import { acquireProviderStream } from './streamShared.js';
-import {
-  getDefaultModelForProvider,
-  getProviderUnavailableMessage,
-  getAvailableProviders,
-  resolveModelSpec,
-} from '../../utils/modelRouting.js';
+import { getAutoModelSpecs, resolveModelSpec } from '../../utils/modelRouting.js';
+import { shouldFailoverToNextProvider } from './parallel.js';
 
 /**
  * Render a stored transcript (from prior laps or a prior chat/consensus thread)
@@ -169,7 +165,9 @@ export function formatLapTranscript(lapTurns) {
  * Resolve the ordered model list into a turn plan. Unlike the parallel engine,
  * unknown or unavailable models are NOT dropped — they are recorded with a
  * preFailReason so they keep their position in the order (and produce a failed
- * turn).
+ * turn). A bare model name served by several providers carries every serving
+ * provider in `candidates`, tried in order when a turn fails with a
+ * failover-worthy error.
  * @param {Array<string>} models - Ordered model list
  * @param {object} providers - Provider instances
  * @param {object} config - Configuration
@@ -181,16 +179,14 @@ export function resolveTurnPlan(models, providers, config, hasImages = false) {
   // (a single-model round-table is valid). Multiple explicit models resolve per-entry.
   let modelsToProcess = models;
   if (models.length === 1 && String(models[0]).toLowerCase() === 'auto') {
-    const [firstAvailable] = getAvailableProviders(providers, config, {
+    const [firstAvailable] = getAutoModelSpecs(providers, config, {
       hasImages,
       limit: 1,
     });
 
     // If a provider is available, use its default model. Otherwise keep "auto"
     // so it resolves to a turn that fails cleanly (all-fail laps must complete).
-    modelsToProcess = firstAvailable
-      ? [getDefaultModelForProvider(firstAvailable)]
-      : ['auto'];
+    modelsToProcess = firstAvailable ? [firstAvailable] : ['auto'];
   }
 
   return modelsToProcess.map((modelName) => {
@@ -200,39 +196,31 @@ export function resolveTurnPlan(models, providers, config, hasImages = false) {
         provider: null,
         providerInstance: null,
         resolvedModel: null,
+        candidates: [],
         preFailReason: 'Invalid model specification',
       };
     }
 
-    const { providerName, provider, resolvedModel, status, options } =
-      resolveModelSpec(modelName, providers, config);
+    const resolution = resolveModelSpec(modelName, providers, config);
 
-    if (status === 'not_found') {
+    if (resolution.status !== 'ok') {
       return {
         model: modelName,
-        provider: providerName,
+        provider: resolution.providerName,
         providerInstance: null,
-        resolvedModel,
-        preFailReason: `Provider not found: ${providerName}`,
-      };
-    }
-
-    if (status === 'unavailable') {
-      return {
-        model: modelName,
-        provider: providerName,
-        providerInstance: null,
-        resolvedModel,
-        preFailReason: getProviderUnavailableMessage(providerName),
+        resolvedModel: null,
+        candidates: [],
+        preFailReason: resolution.error,
       };
     }
 
     return {
       model: modelName,
-      provider: providerName,
-      providerInstance: provider,
-      resolvedModel,
-      resolveOptions: options,
+      provider: resolution.providerName,
+      providerInstance: resolution.provider,
+      resolvedModel: resolution.resolvedModel,
+      resolveOptions: resolution.options,
+      candidates: resolution.candidates,
       preFailReason: null,
     };
   });
@@ -254,7 +242,9 @@ function buildTurnUserContent(packetText, contextMessage) {
  * Execute a single turn. Streams (updating job progress) when a job context is
  * present; otherwise performs a plain invoke. Cancellation propagates by throwing
  * so the lap aborts rather than demoting to a failed turn.
- * @returns {Promise<object>} Turn result { model, provider, status, response|error }
+ * @returns {Promise<object>} Turn result { model, provider, status, response|error };
+ *   failed turns also carry the thrown `cause` for the failover decision
+ *   (stripped before the turn is recorded)
  */
 async function executeTurn(
   plan,
@@ -353,6 +343,7 @@ async function executeTurn(
       provider: plan.provider,
       status: 'failed',
       error: error.message,
+      cause: error,
     };
   }
 }
@@ -436,24 +427,44 @@ export async function runRoundtableLap({
         { role: 'user', content: finalUserContent },
       ];
 
-      const turnResult = await executeTurn(
-        plan,
-        messages,
-        {
-          reasoning_effort,
-          signal: activeSignal,
-          config,
-          model: plan.resolvedModel,
-          // Web search opt-in from an OpenRouter `:online` decoration; only ever
-          // set for OpenRouter turns.
-          ...(plan.resolveOptions?.web_search && { web_search: true }),
-        },
-        context,
-        providerStreamNormalizer,
-        i,
-      );
+      let turnResult;
+      for (let ci = 0; ci < plan.candidates.length; ci++) {
+        const candidate = plan.candidates[ci];
+        turnResult = await executeTurn(
+          {
+            model: plan.model,
+            provider: candidate.providerName,
+            providerInstance: candidate.provider,
+          },
+          messages,
+          {
+            reasoning_effort,
+            signal: activeSignal,
+            config,
+            model: candidate.resolvedModel,
+            // Web search opt-in from an OpenRouter `:online` decoration; only ever
+            // set for OpenRouter turns.
+            ...(candidate.options?.web_search && { web_search: true }),
+          },
+          context,
+          providerStreamNormalizer,
+          i,
+        );
+        const isLastCandidate = ci === plan.candidates.length - 1;
+        if (
+          turnResult.status === 'success' ||
+          isLastCandidate ||
+          !shouldFailoverToNextProvider(turnResult.cause)
+        ) {
+          break;
+        }
+        debugLog(
+          `[Roundtable] Turn ${i + 1} (${plan.model}) failed on ${candidate.providerName}; failing over`,
+        );
+      }
 
-      lapTurns.push({ ...turnResult, position: i });
+      const { cause: _cause, ...turn } = turnResult;
+      lapTurns.push({ ...turn, position: i });
     }
 
     if (context) {

package/src/utils/localProviderAuth.js

@@ -0,0 +1,63 @@
+/**
+ * Local Provider Availability Probes
+ *
+ * Cheap, synchronous checks for the CLI/SDK providers: the SDK package
+ * resolves and a credential is present. They never spawn a process or call a
+ * network endpoint, so they cannot prove a login is still valid — a stale
+ * credential surfaces as an auth error at invoke time, where bare-name and
+ * "auto" routing fail over to the next provider.
+ */
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const resolvedPackages = new Map();
+
+/**
+ * Whether an npm package resolves from this module. Cached per process:
+ * installing a package requires a restart to load it anyway.
+ * @param {string} packageName
+ * @returns {boolean}
+ */
+export function isPackageResolvable(packageName) {
+  if (!resolvedPackages.has(packageName)) {
+    let resolvable;
+    try {
+      import.meta.resolve(packageName);
+      resolvable = true;
+    } catch {
+      resolvable = false;
+    }
+    resolvedPackages.set(packageName, resolvable);
+  }
+  return resolvedPackages.get(packageName);
+}
+
+/**
+ * Codex credentials: CODEX_API_KEY, or the ChatGPT login file the Codex CLI
+ * writes to $CODEX_HOME/auth.json (default ~/.codex).
+ * @param {object} config
+ * @returns {boolean}
+ */
+export function hasCodexCredentials(config) {
+  if (config?.providers?.codexapikey) return true;
+  const codexHome = process.env.CODEX_HOME || join(homedir(), '.codex');
+  return existsSync(join(codexHome, 'auth.json'));
+}
+
+/**
+ * Claude Code credentials: an OAuth token or API key in the environment the
+ * spawned CLI inherits, or the login file in $CLAUDE_CONFIG_DIR (default
+ * ~/.claude). macOS keeps the login in the Keychain, which cannot be read
+ * without spawning a process, so a login there is assumed.
+ * @returns {boolean}
+ */
+export function hasClaudeCredentials() {
+  if (process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY) {
+    return true;
+  }
+  if (process.platform === 'darwin') return true;
+  const configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+  return existsSync(join(configDir, '.credentials.json'));
+}

package/src/utils/modelCatalog.js

@@ -0,0 +1,38 @@
+/**
+ * Model Catalog Helpers
+ *
+ * Every provider keeps a catalog keyed by canonical model ID, each entry
+ * carrying an `aliases` array. These helpers are the single lookup rule for
+ * those catalogs: case-insensitive, canonical ID first, then aliases.
+ */
+
+/**
+ * Canonical catalog ID for a name, or null.
+ * @param {Object<string, {aliases?: string[]}>} catalog
+ * @param {string} name - Canonical ID or alias
+ * @returns {string|null}
+ */
+export function findCatalogId(catalog, name) {
+  const lower = String(name ?? '').trim().toLowerCase();
+  if (!lower || !catalog) return null;
+  for (const id of Object.keys(catalog)) {
+    if (id.toLowerCase() === lower) return id;
+  }
+  for (const [id, entry] of Object.entries(catalog)) {
+    if (entry?.aliases?.some((alias) => String(alias).toLowerCase() === lower)) {
+      return id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Catalog entry for a name, or null.
+ * @param {Object<string, object>} catalog
+ * @param {string} name - Canonical ID or alias
+ * @returns {object|null}
+ */
+export function findCatalogEntry(catalog, name) {
+  const id = findCatalogId(catalog, name);
+  return id ? catalog[id] : null;
+}