converse-mcp-server 3.7.1 → 4.1.0

package/src/providers/codex.js

@@ -20,10 +20,15 @@ import {
   EFFORT_LADDER,
   clampReasoningEffort,
 } from '../utils/reasoningEffort.js';
+import { findCatalogEntry, findCatalogId } from '../utils/modelCatalog.js';
+import {
+  hasCodexCredentials,
+  isPackageResolvable,
+} from '../utils/localProviderAuth.js';
 
 /**
- * Backend models Codex can run, keyed by the slug passed to the CLI as
- * --model. The reasoning tiers are the ones each model's API accepts, verified
+ * Models Codex can run, keyed by the slug passed to the CLI as --model. The
+ * catalog key is the canonical model ID the router resolves to. The reasoning tiers are the ones each model's API accepts, verified
  * against the API's own rejection messages (gpt-6-astra: "Supported values
  * are: 'low', 'medium', 'high', 'xhigh', and 'max'"; the Sol/Luna tiers of
  * both generations accept 'none' as well). The SDK's ModelReasoningEffort
@@ -38,68 +43,56 @@ import {
  * it reasons — so it is deliberately absent from every supportedEfforts list
  * and nothing at the tool level can select it.
  */
-const CODEX_BACKEND_MODELS = {
-  'gpt-6-sol': {
+const ALL_EFFORTS = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+function codexModel(slug, friendlyName, { aliases, contextWindow = 272000, supportedEfforts = ALL_EFFORTS }) {
+  return {
+    modelName: slug,
+    friendlyName: `OpenAI Codex (${friendlyName})`,
+    contextWindow,
+    maxOutputTokens: 128000,
+    supportsStreaming: true,
+    supportsImages: true, // Codex SDK 0.118+ supports images via --image (local_image input)
+    supportsWebSearch: false, // Codex accesses files directly, not web
+    timeout: 1800000, // 30 minutes
+    description: `${friendlyName} via the Codex agentic coding assistant, with local file access and tool execution`,
+    aliases,
+    supportedEfforts,
+  };
+}
+
+const SUPPORTED_MODELS = {
+  'gpt-6-sol': codexModel('gpt-6-sol', 'GPT-6 Sol', {
     aliases: ['sol', 'gpt-6', 'gpt6', 'gpt6-sol', 'gpt-6-codex'],
-    contextWindow: 272000,
-    supportedEfforts: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
-  },
-  'gpt-6-luna': {
+  }),
+  'gpt-6-luna': codexModel('gpt-6-luna', 'GPT-6 Luna', {
     aliases: ['luna', 'gpt6-luna'],
-    contextWindow: 272000,
-    supportedEfforts: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
-  },
-  'gpt-6-astra': {
+  }),
+  'gpt-6-astra': codexModel('gpt-6-astra', 'GPT-6 Astra', {
     aliases: ['astra', 'gpt6-astra'],
-    contextWindow: 272000,
     supportedEfforts: ['low', 'medium', 'high', 'xhigh', 'max'],
-  },
-  'gpt-5.6-sol': {
+  }),
+  'gpt-5.6-sol': codexModel('gpt-5.6-sol', 'GPT-5.6 Sol', {
     aliases: ['gpt-5.6', 'gpt5.6', 'gpt5.6-sol', 'gpt-5.6-codex'],
-    contextWindow: 272000,
-    supportedEfforts: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
-  },
-  'gpt-5.6-terra': {
+  }),
+  'gpt-5.6-terra': codexModel('gpt-5.6-terra', 'GPT-5.6 Terra', {
     aliases: ['terra', 'gpt5.6-terra'],
-    contextWindow: 272000,
-    supportedEfforts: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
-  },
-  'gpt-5.6-luna': {
+  }),
+  'gpt-5.6-luna': codexModel('gpt-5.6-luna', 'GPT-5.6 Luna', {
     aliases: ['gpt5.6-luna'],
-    contextWindow: 272000,
-    supportedEfforts: ['none', 'low', 'medium', 'high', 'xhigh', 'max'],
-  },
-  'gpt-5.5': {
+  }),
+  'gpt-5.5': codexModel('gpt-5.5', 'GPT-5.5', {
     aliases: ['gpt5.5'],
-    contextWindow: 272000,
     supportedEfforts: ['low', 'medium', 'high', 'xhigh'],
-  },
-  'gpt-5.3-codex-spark': {
+  }),
+  'gpt-5.3-codex-spark': codexModel('gpt-5.3-codex-spark', 'GPT-5.3 Codex Spark', {
     aliases: ['spark', 'codex-spark'],
     contextWindow: 128000,
     supportedEfforts: ['low', 'medium', 'high', 'xhigh'],
-  },
+  }),
 };
 
-const DEFAULT_BACKEND_MODEL = 'gpt-6-sol';
-
-// The single user-facing model the router exposes. The backend model behind it
-// comes from CODEX_MODEL, or from a `codex:<model>` spec.
-const SUPPORTED_MODELS = {
-  codex: {
-    modelName: 'codex',
-    friendlyName: 'OpenAI Codex (GPT-6 Sol)',
-    contextWindow: CODEX_BACKEND_MODELS[DEFAULT_BACKEND_MODEL].contextWindow,
-    maxOutputTokens: 128000,
-    supportsStreaming: true,
-    supportsImages: true, // Codex SDK 0.118+ supports images via --image (local_image input)
-    supportsWebSearch: false, // Codex accesses files directly, not web
-    timeout: 1800000, // 30 minutes
-    description:
-      'OpenAI Codex agentic coding assistant with local file access and tool execution (GPT-6 Sol by default; pick another backend with codex:<model> or CODEX_MODEL)',
-    aliases: [],
-  },
-};
+const DEFAULT_MODEL = 'gpt-6-sol';
 
 /**
  * Custom error class for Codex provider errors
@@ -111,26 +104,14 @@ class CodexProviderError extends ProviderError {
   }
 }
 
-/**
- * Check if Codex SDK is available (optional dependency)
- * Uses import.meta.resolve when available, falls back to filesystem check
- */
-function isCodexAvailable() {
-  try {
-    // Just try to dynamically check if we can import it
-    // This is a simple presence check that works in ES modules
-    return true; // If SDK not available, the actual import() will fail later with clear error
-  } catch {
-    return false;
-  }
-}
+const CODEX_SDK_PACKAGE = '@openai/codex-sdk';
 
 /**
  * Dynamically import Codex SDK (lazy loading)
  * This keeps the SDK as an optional dependency
  */
 async function getCodexSDK() {
-  if (!isCodexAvailable()) {
+  if (!isPackageResolvable(CODEX_SDK_PACKAGE)) {
     throw new CodexProviderError(
       'Codex SDK not installed. Install with: npm install @openai/codex-sdk',
       'CODEX_NOT_INSTALLED',
@@ -248,54 +229,24 @@ function extractPromptText(input) {
 }
 
 /**
- * Resolve a backend slug or alias (case-insensitive) to its catalog slug.
- * @param {string} name
- * @returns {string|null}
+ * Resolve a model name to the slug passed to the CLI. The router hands over
+ * canonical catalog IDs; aliases are accepted for direct callers.
+ * @param {string} [model] - Catalog ID or alias; defaults to DEFAULT_MODEL
+ * @returns {string} Backend slug for the SDK's `model` option
+ * @throws {CodexProviderError} When the name is not in the catalog
  */
-function findBackendSlug(name) {
-  const lower = String(name || '').trim().toLowerCase();
-  if (!lower) {
-    return null;
+export function resolveBackendModel(model) {
+  if (model === undefined || model === null || model === '') {
+    return DEFAULT_MODEL;
   }
-  if (CODEX_BACKEND_MODELS[lower]) {
-    return lower;
+  const slug = findCatalogId(SUPPORTED_MODELS, model);
+  if (!slug) {
+    throw new CodexProviderError(
+      `Unknown Codex model "${model}"`,
+      ErrorCodes.MODEL_NOT_FOUND,
+    );
   }
-  return (
-    Object.keys(CODEX_BACKEND_MODELS).find((slug) =>
-      CODEX_BACKEND_MODELS[slug].aliases.includes(lower),
-    ) || null
-  );
-}
-
-/**
- * Catalog entry for a backend model, or null when the slug is not catalogued.
- * @param {string} name - Backend slug or alias
- * @returns {{ slug: string, aliases: string[], contextWindow: number, supportedEfforts: string[] }|null}
- */
-export function getBackendModelConfig(name) {
-  const slug = findBackendSlug(name);
-  return slug ? { slug, ...CODEX_BACKEND_MODELS[slug] } : null;
-}
-
-/**
- * Resolve the requested model spec to the backend slug passed to the CLI.
- *
- * `codex` uses CODEX_MODEL (default gpt-6-sol); `codex:<model>` names a
- * backend directly, by slug or alias. Unknown names pass through verbatim so a
- * newly released model works before it is catalogued here — the CLI rejects
- * anything the backend does not know.
- *
- * @param {string} spec - Requested model, e.g. 'codex' or 'codex:sol'
- * @param {Object} [config] - Loaded configuration
- * @returns {string} Backend slug for the SDK's `model` option
- */
-export function resolveBackendModel(spec, config) {
-  const raw = String(spec || '').trim();
-  const requested = raw.toLowerCase().startsWith('codex:')
-    ? raw.slice('codex:'.length).trim()
-    : '';
-  const name = requested || config?.providers?.codexmodel || DEFAULT_BACKEND_MODEL;
-  return findBackendSlug(name) || name;
+  return slug;
 }
 
 /**
@@ -319,30 +270,6 @@ async function getThreadIdFromContinuation(
   }
 }
 
-/**
- * Resolve a user-facing model name to its entry in SUPPORTED_MODELS.
- * @param {string} modelName
- * @returns {Object|null}
- */
-function findModelConfig(modelName) {
-  const modelNameLower = String(modelName || '').toLowerCase();
-
-  if (SUPPORTED_MODELS[modelNameLower]) {
-    return SUPPORTED_MODELS[modelNameLower];
-  }
-
-  for (const config of Object.values(SUPPORTED_MODELS)) {
-    if (
-      config.aliases &&
-      config.aliases.some((alias) => alias.toLowerCase() === modelNameLower)
-    ) {
-      return config;
-    }
-  }
-
-  return null;
-}
-
 /**
  * Create stream generator for Codex streaming responses.
  * `input` is the Codex SDK Input (string | UserInput[]) — strings for plain
@@ -382,7 +309,7 @@ export const codexProvider = {
    */
   async invoke(messages, options = {}) {
     const {
-      model = 'codex',
+      model = DEFAULT_MODEL,
       config,
       stream = false,
       signal,
@@ -400,6 +327,10 @@ export const codexProvider = {
       );
     }
 
+    // Resolved outside the try so an unknown model keeps MODEL_NOT_FOUND
+    // instead of being rewrapped as a generic execution failure.
+    const backendModel = resolveBackendModel(model);
+
     try {
       // Get Codex SDK
       const Codex = await getCodexSDK();
@@ -456,7 +387,6 @@ export const codexProvider = {
       const approvalPolicy = config.providers?.codexapprovalpolicy || 'never';
 
       // Create or resume thread
-      const backendModel = resolveBackendModel(model, config);
       const threadOptions = {
         model: backendModel,
         workingDirectory,
@@ -467,7 +397,7 @@ export const codexProvider = {
 
       if (reasoning_effort) {
         const supportedEfforts =
-          getBackendModelConfig(backendModel)?.supportedEfforts || EFFORT_LADDER;
+          SUPPORTED_MODELS[backendModel]?.supportedEfforts || EFFORT_LADDER;
         const mappedEffort = clampReasoningEffort(reasoning_effort, supportedEfforts);
         threadOptions.modelReasoningEffort = mappedEffort;
         if (mappedEffort !== reasoning_effort) {
@@ -575,15 +505,14 @@ export const codexProvider = {
     }
   },
 
+  defaultModel: DEFAULT_MODEL,
+
   /**
-   * Validate Codex configuration
-   * Codex uses ChatGPT authentication or CODEX_API_KEY (NOT OPENAI_API_KEY)
+   * Validate Codex configuration: the SDK is installed and a credential is
+   * present (ChatGPT login file or CODEX_API_KEY — NOT OPENAI_API_KEY).
    */
-  validateConfig(_config) {
-    // Codex can work with either ChatGPT login or API key
-    // Since we can't reliably check ChatGPT login status, we'll be permissive
-    // and let the SDK handle authentication errors
-    return isCodexAvailable();
+  validateConfig(config) {
+    return isPackageResolvable(CODEX_SDK_PACKAGE) && hasCodexCredentials(config);
   },
 
   /**
@@ -604,6 +533,6 @@ export const codexProvider = {
    * Get model configuration for specific model
    */
   getModelConfig(modelName) {
-    return findModelConfig(modelName);
+    return findCatalogEntry(SUPPORTED_MODELS, modelName);
   },
 };

package/src/providers/copilot.js

@@ -18,29 +18,19 @@ import { fileURLToPath } from 'node:url';
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
 import { clampReasoningEffort } from '../utils/reasoningEffort.js';
+import { findCatalogEntry, findCatalogId } from '../utils/modelCatalog.js';
+import { isPackageResolvable } from '../utils/localProviderAuth.js';
 
-const SUPPORTED_MODELS = {
-  copilot: {
-    modelName: 'copilot',
-    friendlyName: 'GitHub Copilot (via CLI SDK)',
-    contextWindow: 128000,
-    maxOutputTokens: 16384,
-    supportsStreaming: true,
-    supportsImages: false,
-    supportsWebSearch: false,
-    timeout: 1800000,
-    description:
-			'GitHub Copilot via CLI SDK - uses default or env-configured model',
-    aliases: ['copilot-sdk', 'github-copilot'],
-  },
+const DEFAULT_MODEL = 'gpt-6-sol';
 
+// Keyed by the SDK model ID, which is also the canonical ID the router
+// resolves to. Every name here is reached only through the `copilot:`
+// namespace — Copilot never serves bare model names.
+const SUPPORTED_MODELS = {
   // OpenAI models
-  // Bare `gpt-6` / `gpt-5.6` route to that generation's Sol, matching
-  // Copilot's own bare-alias behavior; `sol`/`luna` and the legacy `gpt-5`
-  // shortcut follow the current generation. `codex` and `gpt` point at the
-  // latest GPT tier (reachable only via the `copilot:` namespace — bare
-  // `codex` routes to the Codex provider and bare `gpt*` keyword-routes to
-  // OpenAI before Copilot's catalog is consulted).
+  // `gpt-6` / `gpt-5.6` point at that generation's Sol, matching Copilot's own
+  // bare-alias behavior; `sol`/`luna` and the legacy `gpt-5` shortcut follow
+  // the current generation. `codex` and `gpt` point at the latest GPT tier.
   'gpt-6-sol': {
     modelName: 'gpt-6-sol',
     friendlyName: 'GPT-6 Sol (via Copilot)',
@@ -205,22 +195,6 @@ class CopilotProviderError extends ProviderError {
   }
 }
 
-/**
- * Check if Copilot SDK is available (installed as dependency)
- */
-let _sdkAvailable = null;
-function isCopilotSDKAvailable() {
-  if (_sdkAvailable !== null) return _sdkAvailable;
-  try {
-    // Use synchronous resolve to check if the package exists
-    import.meta.resolve('@github/copilot-sdk');
-    _sdkAvailable = true;
-  } catch {
-    _sdkAvailable = false;
-  }
-  return _sdkAvailable;
-}
-
 /**
  * Dynamically import Copilot SDK (lazy loading)
  */
@@ -443,106 +417,24 @@ function createPermissionHandler(accessLevel) {
 }
 
 /**
- * Resolve a friendly alias to its SDK model identifier (case-insensitive)
- * Returns the resolved model name, or null if no alias matches
- */
-function resolveModelAlias(name) {
-  if (typeof name !== 'string') return null;
-  const lower = name.toLowerCase().trim();
-  if (!lower) return null;
-
-  // Direct key match
-  if (SUPPORTED_MODELS[lower] && lower !== 'copilot') {
-    return SUPPORTED_MODELS[lower].modelName;
-  }
-
-  // Alias match
-  for (const config of Object.values(SUPPORTED_MODELS)) {
-    if (config.modelName === 'copilot') continue;
-    if (
-      config.aliases &&
-			config.aliases.some((alias) => alias.toLowerCase() === lower)
-    ) {
-      return config.modelName;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Look up model config from SUPPORTED_MODELS by name or alias.
- * Strips copilot: prefix and falls back to the base copilot config.
- */
-function findModelConfig(modelName) {
-  if (typeof modelName !== 'string') return null;
-
-  let name = modelName;
-  if (name.toLowerCase().startsWith('copilot:')) {
-    name = name.slice('copilot:'.length).trim();
-  }
-  if (!name) return SUPPORTED_MODELS.copilot;
-
-  const nameLower = name.toLowerCase();
-
-  if (SUPPORTED_MODELS[nameLower]) {
-    return SUPPORTED_MODELS[nameLower];
-  }
-
-  for (const config of Object.values(SUPPORTED_MODELS)) {
-    if (
-      config.aliases &&
-      config.aliases.some((alias) => alias.toLowerCase() === nameLower)
-    ) {
-      return config;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Resolve model to pass to SDK session
- * Precedence: explicit model param > config COPILOT_MODEL > omit (SDK default)
- *
- * Handles copilot: prefix stripping, alias resolution, and env var fallback.
- * Note: "copilot" is a Converse routing alias, not a valid SDK model ID.
+ * Resolve a model name to the SDK model ID for the session. The router hands
+ * over canonical catalog IDs; aliases are accepted for direct callers.
+ * @param {string} [model] - Catalog ID or alias; defaults to DEFAULT_MODEL
+ * @returns {string}
+ * @throws {CopilotProviderError} When the name is not in the catalog
  */
-function resolveSessionModel(requestModel, config) {
-  const converseAliases = ['copilot', 'copilot-sdk', 'github-copilot'];
-
-  // Guard non-string inputs
-  if (typeof requestModel !== 'string') {
-    requestModel = '';
+function resolveSessionModel(model) {
+  if (typeof model !== 'string' || !model.trim()) {
+    return DEFAULT_MODEL;
   }
-
-  // Strip copilot: prefix (case-insensitive)
-  let effectiveModel = requestModel;
-  if (effectiveModel.toLowerCase().startsWith('copilot:')) {
-    effectiveModel = effectiveModel.slice('copilot:'.length).trim();
-  }
-
-  // Empty suffix or converse alias → use env/default
-  if (
-    !effectiveModel ||
-		converseAliases.includes(effectiveModel.toLowerCase())
-  ) {
-    const envModel = config?.providers?.copilotmodel;
-    if (envModel) {
-      let resolved = typeof envModel === 'string' ? envModel : '';
-      if (resolved.toLowerCase().startsWith('copilot:')) {
-        resolved = resolved.slice('copilot:'.length).trim();
-      }
-      if (!resolved || converseAliases.includes(resolved.toLowerCase())) {
-        return undefined;
-      }
-      return resolveModelAlias(resolved) || resolved;
-    }
-    return undefined;
+  const id = findCatalogId(SUPPORTED_MODELS, model);
+  if (!id) {
+    throw new CopilotProviderError(
+      `Unknown Copilot model "${model}"`,
+      ErrorCodes.MODEL_NOT_FOUND,
+    );
   }
-
-  // Resolve alias or passthrough unknown models to SDK
-  return resolveModelAlias(effectiveModel) || effectiveModel;
+  return SUPPORTED_MODELS[id].modelName;
 }
 
 /**
@@ -590,23 +482,20 @@ async function checkReasoningSupport(client, modelId) {
 async function* createStreamingGenerator(client, prompt, options, signal, config) {
   const { model, timeout = 1800000, reasoning_effort } = options;
 
-  const sessionModel = resolveSessionModel(model, config);
+  const sessionModel = resolveSessionModel(model);
   const accessLevel = getToolAccessLevel(config);
 
   const sessionConfig = {
     streaming: true,
     onPermissionRequest: createPermissionHandler(accessLevel),
+    model: sessionModel,
   };
 
-  if (sessionModel) {
-    sessionConfig.model = sessionModel;
-  }
-
   if (reasoning_effort) {
     const mapped = mapReasoningEffort(reasoning_effort);
     if (mapped) {
-      const effectiveModel = sessionModel || model;
-      const modelDef = findModelConfig(effectiveModel);
+      const effectiveModel = sessionModel;
+      const modelDef = SUPPORTED_MODELS[sessionModel];
 
       let supported;
       if (modelDef && modelDef.supportsReasoningEffort !== undefined) {
@@ -650,7 +539,7 @@ async function* createStreamingGenerator(client, prompt, options, signal, config
     yield {
       type: 'start',
       provider: 'copilot',
-      model: sessionModel || 'copilot',
+      model: sessionModel,
     };
 
     // Bridge push-based SDK events to pull-based generator using queue + promise
@@ -775,7 +664,7 @@ async function* createStreamingGenerator(client, prompt, options, signal, config
   }
 }
 
-export { resolveModelAlias, resolveSessionModel, resolveCopilotCliPath };
+export { resolveSessionModel, resolveCopilotCliPath };
 
 /**
  * Copilot SDK Provider Implementation
@@ -783,7 +672,7 @@ export { resolveModelAlias, resolveSessionModel, resolveCopilotCliPath };
 export const copilotProvider = {
   async invoke(messages, options = {}) {
     const {
-      model = 'copilot',
+      model = DEFAULT_MODEL,
       config,
       stream = false,
       signal,
@@ -797,15 +686,17 @@ export const copilotProvider = {
       );
     }
 
+    // Validated before the client spawns the Copilot CLI.
+    const sessionModel = resolveSessionModel(model);
+
     try {
       const cwd = config.server?.client_cwd || process.cwd();
       const client = await getCopilotClient(cwd, config);
       const prompt = convertMessagesToPrompt(messages);
 
-      const sessionModel = resolveSessionModel(model, config);
-      const modelConfig = findModelConfig(sessionModel || model) || SUPPORTED_MODELS.copilot;
+      const modelConfig = SUPPORTED_MODELS[sessionModel];
       const invokeOptions = {
-        model,
+        model: sessionModel,
         timeout: modelConfig.timeout,
         reasoning_effort,
       };
@@ -843,7 +734,7 @@ export const copilotProvider = {
         rawResponse: { content, usage },
         metadata: {
           provider: 'copilot',
-          model: sessionModel || 'copilot',
+          model: sessionModel,
           usage: usage
             ? {
               input_tokens: usage.input_tokens || 0,
@@ -901,12 +792,14 @@ export const copilotProvider = {
     }
   },
 
+  defaultModel: DEFAULT_MODEL,
+
   /**
    * Validate Copilot SDK configuration
    * Returns true optimistically — auth errors surface at runtime
    */
   validateConfig(_config) {
-    return isCopilotSDKAvailable();
+    return isPackageResolvable('@github/copilot-sdk');
   },
 
   isAvailable(config) {
@@ -918,6 +811,6 @@ export const copilotProvider = {
   },
 
   getModelConfig(modelName) {
-    return findModelConfig(modelName);
+    return findCatalogEntry(SUPPORTED_MODELS, modelName);
   },
 };

package/src/providers/deepseek.js

@@ -140,6 +140,7 @@ export const deepseekProvider = createOpenAICompatibleProvider({
   baseURL: 'https://api.deepseek.com',
   providerName: 'DeepSeek',
   supportedModels: SUPPORTED_MODELS,
+  defaultModel: 'deepseek-v4-pro',
   validateApiKey,
   transformRequest,
   transformResponse,