converse-mcp-server 3.7.1 → 4.0.0

package/src/providers/claude.js

@@ -16,14 +16,20 @@
 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 {
+  hasClaudeCredentials,
+  isPackageResolvable,
+} from '../utils/localProviderAuth.js';
 
-// Default underlying model when the request is just "claude" (or "claude:opus")
-const DEFAULT_SDK_MODEL = 'claude-opus-5-5';
+const DEFAULT_MODEL = 'claude-opus-5-5';
 const SDK_EFFORT_TIERS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const CLAUDE_SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk';
 
-// Supported Claude SDK models with their configurations
+// Keyed by the model ID the Agent SDK accepts, which is also the canonical ID
+// the router resolves to.
 const SUPPORTED_MODELS = {
-  opus: {
+  'claude-opus-5-5': {
     modelName: 'claude-opus-5-5',
     friendlyName: 'Claude Opus 5.5 (via Agent SDK)',
     contextWindow: 1000000,
@@ -35,18 +41,14 @@ const SUPPORTED_MODELS = {
     description:
       'Claude Opus 5.5 via Agent SDK (default) - requires claude login authentication',
     aliases: [
-      'claude',
-      'claude-sdk',
-      'claude-code',
-      'claude:opus',
+      'opus',
       'claude-opus',
-      'claude-opus-5-5',
       'claude-opus-5.5',
       'opus-5-5',
       'opus-5.5',
     ],
   },
-  'opus-5': {
+  'claude-opus-5': {
     modelName: 'claude-opus-5',
     friendlyName: 'Claude Opus 5 (via Agent SDK)',
     contextWindow: 1000000,
@@ -57,9 +59,9 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     description:
       'Claude Opus 5 via Agent SDK - requires claude login authentication',
-    aliases: ['claude-opus-5'],
+    aliases: ['opus-5', 'opus5'],
   },
-  fable: {
+  'claude-fable-5-1': {
     modelName: 'claude-fable-5-1',
     friendlyName: 'Claude Fable 5.1 (via Agent SDK)',
     contextWindow: 1000000,
@@ -71,15 +73,14 @@ const SUPPORTED_MODELS = {
     description:
       'Claude Fable 5.1 via Agent SDK - requires claude login authentication',
     aliases: [
-      'claude:fable',
+      'fable',
       'claude-fable',
-      'claude-fable-5-1',
       'claude-fable-5.1',
       'fable-5-1',
       'fable-5.1',
     ],
   },
-  'fable-5': {
+  'claude-fable-5': {
     modelName: 'claude-fable-5',
     friendlyName: 'Claude Fable 5 (via Agent SDK)',
     contextWindow: 1000000,
@@ -90,7 +91,7 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     description:
       'Claude Fable 5 via Agent SDK - requires claude login authentication',
-    aliases: ['claude-fable-5'],
+    aliases: ['fable-5', 'fable5'],
   },
 };
 
@@ -104,25 +105,12 @@ class ClaudeProviderError extends ProviderError {
   }
 }
 
-/**
- * Check if Claude SDK is available (optional dependency)
- */
-function isClaudeSDKAvailable() {
-  try {
-    // Simple presence check that works in ES modules
-    // If SDK not available, the actual import() will fail later with clear error
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Dynamically import Claude SDK (lazy loading)
  * This keeps the SDK as an optional dependency
  */
 async function getClaudeSDK() {
-  if (!isClaudeSDKAvailable()) {
+  if (!isPackageResolvable(CLAUDE_SDK_PACKAGE)) {
     throw new ClaudeProviderError(
       'Claude SDK not installed. Install with: npm install @anthropic-ai/claude-agent-sdk',
       'CLAUDE_SDK_NOT_INSTALLED',
@@ -143,58 +131,24 @@ async function getClaudeSDK() {
 }
 
 /**
- * Look up model config from SUPPORTED_MODELS by name or alias.
- * Strips the claude: prefix first (e.g. "claude:opus" -> "opus").
- */
-function findModelConfig(modelName) {
-  if (typeof modelName !== 'string') return null;
-
-  let name = modelName.trim();
-  if (name.toLowerCase().startsWith('claude:')) {
-    name = name.slice('claude:'.length).trim();
-  }
-  if (!name) return SUPPORTED_MODELS.opus;
-
-  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 the requested model to the underlying SDK model ID.
- * - "claude" (and bare "claude:") defaults to Claude Opus 5.5
- * - "claude:opus" / "claude:opus-5" / "claude:fable" / "claude:fable-5" select the specific model
- * - Unknown names are passed through (after prefix stripping) so users can
- *   target any model ID the Agent SDK accepts (e.g. "claude:claude-sonnet-4-6")
+ * Resolve a model name to the Agent SDK model ID. The router hands over
+ * canonical catalog IDs; aliases are accepted for direct callers.
+ * @param {string} [modelName] - Catalog ID or alias; defaults to DEFAULT_MODEL
+ * @returns {string}
+ * @throws {ClaudeProviderError} When the name is not in the catalog
  */
 function resolveSdkModel(modelName) {
   if (typeof modelName !== 'string' || !modelName.trim()) {
-    return DEFAULT_SDK_MODEL;
+    return DEFAULT_MODEL;
   }
-
-  const config = findModelConfig(modelName);
-  if (config) {
-    return config.modelName;
-  }
-
-  let name = modelName.trim();
-  if (name.toLowerCase().startsWith('claude:')) {
-    name = name.slice('claude:'.length).trim();
+  const id = findCatalogId(SUPPORTED_MODELS, modelName);
+  if (!id) {
+    throw new ClaudeProviderError(
+      `Unknown Claude model "${modelName}"`,
+      ErrorCodes.MODEL_NOT_FOUND,
+    );
   }
-  return name || DEFAULT_SDK_MODEL;
+  return SUPPORTED_MODELS[id].modelName;
 }
 
 /**
@@ -338,7 +292,7 @@ async function* createStreamingGenerator(
   try {
     const queryOptions = {
       ...options,
-      model: options.model || DEFAULT_SDK_MODEL,
+      model: options.model || DEFAULT_MODEL,
       maxTurns: 100,
       permissionMode: 'bypassPermissions', // Don't prompt for permissions
     };
@@ -475,7 +429,7 @@ export const claudeProvider = {
    */
   async invoke(messages, options = {}) {
     const {
-      model = 'claude',
+      model = DEFAULT_MODEL,
       config,
       stream = false,
       signal,
@@ -616,16 +570,14 @@ export const claudeProvider = {
     }
   },
 
+  defaultModel: DEFAULT_MODEL,
+
   /**
-   * Validate Claude SDK configuration
-   * Claude SDK uses CLI authentication (NOT API keys)
-   * Returns true optimistically - authentication errors handled at runtime
+   * Validate Claude SDK configuration: the SDK is installed and a Claude Code
+   * credential is present. Expired logins surface at invoke time.
    */
   validateConfig(_config) {
-    // Claude SDK uses CLI authentication, not API keys
-    // We can't reliably check auth status, so return true optimistically
-    // and let the SDK handle authentication errors during execution
-    return isClaudeSDKAvailable();
+    return isPackageResolvable(CLAUDE_SDK_PACKAGE) && hasClaudeCredentials();
   },
 
   /**
@@ -644,9 +596,8 @@ export const claudeProvider = {
 
   /**
    * Get model configuration for specific model
-   * Handles claude: prefixed names (e.g. "claude:opus", "claude:fable", "claude:opus-5")
    */
   getModelConfig(modelName) {
-    return findModelConfig(modelName);
+    return findCatalogEntry(SUPPORTED_MODELS, modelName);
   },
 };

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);
   },
 };