converse-mcp-server 2.29.2 → 3.0.1

package/src/providers/interface.js

@@ -32,11 +32,9 @@
  * Options for provider invocation
  * @typedef {Object} InvokeOptions
  * @property {string} [model] - Model identifier (provider-specific)
- * @property {number} [temperature] - Sampling temperature (0.0-2.0)
  * @property {number} [maxTokens] - Maximum tokens to generate
  * @property {boolean} [stream] - Whether to stream the response
  * @property {string} [reasoning_effort] - Reasoning depth for thinking models
- * @property {boolean} [use_websearch] - Enable web search if supported
  * @property {AbortSignal} [signal] - AbortSignal for cancelling requests
  * @property {Object} config - Provider configuration
  * @property {Object} config.apiKeys - API keys for providers
@@ -69,7 +67,6 @@
  * @property {number} maxOutputTokens - Maximum output tokens
  * @property {boolean} supportsStreaming - Whether streaming is supported
  * @property {boolean} supportsImages - Whether images are supported
- * @property {boolean} supportsTemperature - Whether temperature is supported
  * @property {boolean} [supportsWebSearch] - Whether web search is supported
  * @property {boolean} [supportsThinking] - Whether thinking/reasoning is supported
  * @property {number} [maxThinkingTokens] - Maximum thinking tokens

package/src/providers/mistral.js

@@ -8,73 +8,141 @@
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
 
-// Define supported Mistral models with their capabilities
+// Define supported Mistral models with their capabilities.
+// Reasoning (`reasoning_effort`) is supported only on Medium 3.5 and Small 4;
+// Mistral Large 3 has no adjustable reasoning (see resolveReasoningEffort).
 const SUPPORTED_MODELS = {
-  'magistral-medium-2509': {
-    modelName: 'magistral-medium-2509',
-    friendlyName: 'Magistral Medium 1.2',
-    contextWindow: 128000,
+  'mistral-medium-3-5': {
+    modelName: 'mistral-medium-3-5',
+    friendlyName: 'Mistral Medium 3.5',
+    contextWindow: 262144,
     maxOutputTokens: 32768,
     supportsStreaming: true,
-    supportsImages: true, // Version 1.2 adds vision support
-    supportsTemperature: true,
+    supportsImages: true,
     supportsWebSearch: false,
     supportsReasoning: true,
     timeout: 300000,
     description:
-      'Magistral Medium 1.2 - Frontier-class reasoning model with vision support (September 2025)',
+      'Mistral Medium 3.5 - Frontier-class multimodal model with adjustable reasoning',
     aliases: [
-      'magistral-medium',
-      'magistral-medium-latest',
-      'magistral',
-      'magistral medium',
-      'magistral-medium-1.2',
+      'mistral',
+      'mistral-medium',
+      'mistral-medium-latest',
+      'mistral-medium-3.5',
     ],
   },
-  'magistral-small-2509': {
-    modelName: 'magistral-small-2509',
-    friendlyName: 'Magistral Small 1.2',
-    contextWindow: 128000,
+  'mistral-small-2603': {
+    modelName: 'mistral-small-2603',
+    friendlyName: 'Mistral Small 4',
+    contextWindow: 262144,
     maxOutputTokens: 32768,
     supportsStreaming: true,
-    supportsImages: true, // Version 1.2 adds vision support
-    supportsTemperature: true,
+    supportsImages: true,
     supportsWebSearch: false,
     supportsReasoning: true,
     timeout: 180000,
     description:
-      'Magistral Small 1.2 - Small reasoning model with vision support (September 2025)',
-    aliases: [
-      'magistral-small',
-      'magistral-small-latest',
-      'magistral small',
-      'magistral-small-1.2',
-    ],
+      'Mistral Small 4 - Hybrid multimodal model unifying instruct, reasoning, and coding',
+    aliases: ['mistral-small', 'mistral-small-latest'],
   },
-  'mistral-medium-2508': {
-    modelName: 'mistral-medium-2508',
-    friendlyName: 'Mistral Medium 3.1',
-    contextWindow: 128000,
+  'mistral-large-2512': {
+    modelName: 'mistral-large-2512',
+    friendlyName: 'Mistral Large 3',
+    contextWindow: 262144,
     maxOutputTokens: 32768,
     supportsStreaming: true,
     supportsImages: true,
-    supportsTemperature: true,
     supportsWebSearch: false,
+    supportsReasoning: false,
     timeout: 300000,
     description:
-      'Mistral Medium 3.1 - Frontier-class multimodal model with improved tone and performance (August 2025)',
-    aliases: [
-      'mistral-medium-3.1',
-      'mistral-medium-latest',
-      'mistral-medium',
-      'mistral medium 3.1',
-      'mistral',
-      'medium-3.1',
-      'mistral-medium-3',
-    ],
+      'Mistral Large 3 - Open-weight MoE flagship (no adjustable reasoning)',
+    aliases: ['mistral-large', 'mistral-large-latest'],
   },
 };
 
+/**
+ * Map a Converse reasoning_effort level to Mistral's documented request value.
+ * Mistral documents only "high" and "none". Every enabled level maps to "high"
+ * to preserve enabled-reasoning intent (Converse's default `medium` runs
+ * thinking-on); only `none` disables. Returns null when reasoning must not be
+ * forwarded — i.e. the model does not support it (Large 3) or is an unknown
+ * pass-through ID (capability-gated).
+ */
+function resolveReasoningEffort(level, modelConfig) {
+  if (!modelConfig?.supportsReasoning) {
+    return null;
+  }
+  return level === 'none' ? 'none' : 'high';
+}
+
+/**
+ * Walk a Mistral `message.content` array, separating reasoning (ThinkChunk)
+ * from the visible answer (TextChunk). A ReferenceChunk carries citation
+ * metadata only (reference_ids, no visible text) and is ignored for text.
+ * Any other content-bearing chunk type is unexpected and raises.
+ * @returns {{ text: string, reasoning: string }}
+ */
+function normalizeContentChunks(content) {
+  let text = '';
+  let reasoning = '';
+
+  for (const chunk of content) {
+    const type = chunk?.type;
+    if (type === 'thinking') {
+      for (const inner of chunk.thinking || []) {
+        if (inner?.type === 'text') {
+          reasoning += inner.text || '';
+        }
+      }
+    } else if (type === 'text') {
+      text += chunk.text || '';
+    } else if (type === 'reference') {
+      // Citation metadata (reference_ids) — no visible text; ignore.
+    } else {
+      throw new MistralProviderError(
+        `Unexpected Mistral content chunk type "${type}"`,
+        ErrorCodes.API_ERROR,
+      );
+    }
+  }
+
+  return { text, reasoning };
+}
+
+/**
+ * Convert one streaming `delta.content` array into ordered normalized events.
+ * ThinkChunk → thinking, TextChunk → delta, ReferenceChunk → ignored. Unknown
+ * chunk types in a streamed delta are skipped (non-fatal) rather than aborting
+ * an in-flight stream.
+ * @returns {Array<{ kind: 'delta'|'thinking', text: string }>}
+ */
+function streamEventsFromDelta(delta) {
+  const events = [];
+
+  for (const chunk of delta) {
+    const type = chunk?.type;
+    if (type === 'thinking') {
+      let thinkText = '';
+      for (const inner of chunk.thinking || []) {
+        if (inner?.type === 'text') {
+          thinkText += inner.text || '';
+        }
+      }
+      if (thinkText) {
+        events.push({ kind: 'thinking', text: thinkText });
+      }
+    } else if (type === 'text') {
+      if (chunk.text) {
+        events.push({ kind: 'delta', text: chunk.text });
+      }
+    }
+    // ReferenceChunk and any unknown chunk type carry no visible delta text.
+  }
+
+  return events;
+}
+
 /**
  * Map Mistral finish reasons to unified format
  */
@@ -256,16 +324,13 @@ export const mistralProvider = {
    */
   async invoke(messages, options = {}) {
     const {
-      model = 'magistral-medium-2509',
-      temperature = 0.7,
+      model = 'mistral-medium-3-5',
       maxTokens = null,
       stream = false,
-      // eslint-disable-next-line no-unused-vars
-      reasoning_effort = 'medium', // Not supported by Mistral, ignored
-      // eslint-disable-next-line no-unused-vars
-      use_websearch = false, // Not supported by Mistral, ignored
+      reasoning_effort = 'medium',
       config,
       // Filter out options not meant for the API
+      web_search, // eslint-disable-line no-unused-vars
       continuation_id, // eslint-disable-line no-unused-vars
       continuationStore, // eslint-disable-line no-unused-vars
       ...otherOptions
@@ -323,9 +388,11 @@ export const mistralProvider = {
       ...otherOptions,
     };
 
-    // Add temperature if specified
-    if (temperature !== undefined) {
-      requestPayload.temperature = Math.max(0, Math.min(1, temperature));
+    // Forward reasoning effort only when the resolved model supports it
+    // (Mistral Large 3 and unknown pass-through IDs receive no reasoning param).
+    const reasoningEffort = resolveReasoningEffort(reasoning_effort, modelConfig);
+    if (reasoningEffort) {
+      requestPayload.reasoning_effort = reasoningEffort;
     }
 
     // Add max tokens if specified
@@ -370,8 +437,24 @@ export const mistralProvider = {
         );
       }
 
-      const content = choice.message?.content;
-      if (!content) {
+      // Content may be a plain string or an array of ThinkChunk/TextChunk/
+      // ReferenceChunk (when reasoning_effort="high" or citations are used).
+      const rawContent = choice.message?.content;
+      let content = '';
+      let reasoningContent = '';
+      if (typeof rawContent === 'string') {
+        content = rawContent;
+      } else if (Array.isArray(rawContent)) {
+        const parsed = normalizeContentChunks(rawContent);
+        content = parsed.text;
+        reasoningContent = parsed.reasoning;
+      }
+
+      // A reasoning turn may carry empty visible content but present reasoning
+      // or tool calls — accept those (an empty tool_calls array does not count).
+      const toolCalls = choice.message?.tool_calls;
+      const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
+      if (!content && !reasoningContent && !hasToolCalls) {
         throw new MistralProviderError(
           'No content in response from Mistral',
           ErrorCodes.NO_RESPONSE_CONTENT,
@@ -404,6 +487,7 @@ export const mistralProvider = {
           finish_reason: finishReason,
           provider: 'mistral',
           rate_limit: rateLimitInfo,
+          ...(reasoningContent && { reasoning_content: reasoningContent }),
         },
       };
     } catch (error) {
@@ -476,14 +560,14 @@ export const mistralProvider = {
    * @param {Object} mistral - Mistral client instance
    * @param {Object} requestPayload - Request payload for the API
    * @param {string} resolvedModel - Resolved model name
-   * @param {Object} modelConfig - Model configuration
+   * @param {Object} _modelConfig - Model configuration (reserved)
    * @returns {AsyncGenerator} - Streaming generator yielding events
    */
   async *_createStreamingGenerator(
     mistral,
     requestPayload,
     resolvedModel,
-    modelConfig,
+    _modelConfig,
   ) {
     debugLog(
       `[Mistral] Starting streaming for ${resolvedModel} with ${requestPayload.messages?.length} messages`,
@@ -512,17 +596,39 @@ export const mistralProvider = {
           // Mistral wraps the response in a "data" field
           const chunkData = chunk.data || chunk;
 
-          // Extract content from the chunk
+          // Extract content from the chunk. delta.content may be a plain
+          // string (answer phase / reasoning_effort="none"), a list of
+          // ThinkChunks (thinking phase), or a mixed list carrying a closing
+          // ThinkChunk plus the first TextChunk in one delta (transition).
           const choice = chunkData.choices?.[0];
           if (choice) {
-            const content = choice.delta?.content || '';
-            if (content) {
-              totalContent += content;
-              yield {
-                type: 'delta',
-                content,
-                timestamp: new Date().toISOString(),
-              };
+            const delta = choice.delta?.content;
+            if (typeof delta === 'string') {
+              if (delta) {
+                totalContent += delta;
+                yield {
+                  type: 'delta',
+                  content: delta,
+                  timestamp: new Date().toISOString(),
+                };
+              }
+            } else if (Array.isArray(delta)) {
+              for (const event of streamEventsFromDelta(delta)) {
+                if (event.kind === 'delta') {
+                  totalContent += event.text;
+                  yield {
+                    type: 'delta',
+                    content: event.text,
+                    timestamp: new Date().toISOString(),
+                  };
+                } else {
+                  yield {
+                    type: 'thinking',
+                    content: event.text,
+                    timestamp: new Date().toISOString(),
+                  };
+                }
+              }
             }
 
             // Capture finish reason when available

package/src/providers/openai-compatible.js

@@ -270,6 +270,8 @@ export function createOpenAICompatibleProvider(providerConfig) {
     validateApiKey = defaultValidateApiKey,
     transformRequest,
     transformResponse,
+    transformStreamChunk,
+    resolveModelConfig,
     defaultParams = {},
   } = providerConfig;
 
@@ -288,18 +290,17 @@ export function createOpenAICompatibleProvider(providerConfig) {
     async invoke(messages, options = {}) {
       const {
         model = Object.keys(supportedModels)[0], // Default to first model
-        temperature = 0.7,
         maxTokens = null,
         stream = false,
-        // eslint-disable-next-line no-unused-vars
         reasoning_effort = 'medium',
-        // eslint-disable-next-line no-unused-vars
-        use_websearch = false,
         signal,
         config,
         // Filter out options not meant for the API
         continuation_id, // eslint-disable-line no-unused-vars
         continuationStore, // eslint-disable-line no-unused-vars
+        // Consumed by provider invoke overrides (e.g. OpenRouter maps this to a
+        // web plugin); never forwarded to the API payload.
+        web_search, // eslint-disable-line no-unused-vars
         ...otherOptions
       } = options;
 
@@ -333,9 +334,24 @@ export function createOpenAICompatibleProvider(providerConfig) {
         },
       };
 
-      // Add timeout if specified in model config
+      // Resolve the model config. A provider may supply an async
+      // resolveModelConfig hook to obtain a request-local config (e.g. dynamic
+      // OpenRouter metadata) — this rides through here and is NEVER merged into
+      // getSupportedModels(). It may throw (e.g. an authoritative catalog-miss)
+      // to fail before inference.
       const resolvedModel = resolveModelName(model, supportedModels);
-      const modelConfig = supportedModels[resolvedModel] || {};
+      let modelConfig = supportedModels[resolvedModel] || {};
+      if (resolveModelConfig) {
+        const dynamicConfig = await resolveModelConfig(resolvedModel, {
+          config,
+          signal,
+        });
+        if (dynamicConfig) {
+          modelConfig = dynamicConfig;
+        }
+      }
+
+      // Add timeout if specified in model config
       if (modelConfig.timeout) {
         clientOptions.timeout = modelConfig.timeout;
       }
@@ -368,15 +384,6 @@ export function createOpenAICompatibleProvider(providerConfig) {
         ...otherOptions,
       };
 
-      // Add temperature if model supports it and not already set by defaultParams
-      if (
-        modelConfig.supportsTemperature !== false &&
-        temperature !== undefined &&
-        !defaultParams.temperature
-      ) {
-        requestPayload.temperature = Math.max(0, Math.min(2, temperature));
-      }
-
       // Add max tokens if specified
       if (maxTokens) {
         requestPayload.max_tokens = Math.min(
@@ -390,14 +397,16 @@ export function createOpenAICompatibleProvider(providerConfig) {
         requestPayload.stream_options = { include_usage: true };
       }
 
-      // Note: Most OpenAI-compatible APIs don't support reasoning_effort or use_websearch
-      // These are silently ignored unless the provider has custom handling
-
-      // Apply custom request transformation if provided
+      // Apply custom request transformation if provided. The context exposes the
+      // requested reasoning effort and abort signal so providers can build
+      // capability-gated reasoning fields; reasoning_effort itself is never
+      // forwarded to the API payload (it is destructured out above).
       if (transformRequest) {
         requestPayload = await transformRequest(requestPayload, {
           model: resolvedModel,
           modelConfig,
+          reasoningEffort: reasoning_effort,
+          signal,
         });
       }
 
@@ -444,8 +453,26 @@ export function createOpenAICompatibleProvider(providerConfig) {
           );
         }
 
-        const content = choice.message?.content;
-        if (!content) {
+        // A reasoning turn may carry empty visible content but present
+        // reasoning_content / reasoning_details / tool_calls — accept those and
+        // normalize nullable content to ''. An empty array does not count as
+        // present merely for being truthy.
+        const rawContent = choice.message?.content;
+        const reasoningContent = choice.message?.reasoning_content;
+        const reasoningDetails = choice.message?.reasoning_details;
+        const toolCalls = choice.message?.tool_calls;
+        const content = typeof rawContent === 'string' ? rawContent : '';
+        const hasReasoningContent =
+          typeof reasoningContent === 'string' && reasoningContent.length > 0;
+        const hasReasoningDetails =
+          Array.isArray(reasoningDetails) && reasoningDetails.length > 0;
+        const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
+        if (
+          content.length === 0 &&
+          !hasReasoningContent &&
+          !hasReasoningDetails &&
+          !hasToolCalls
+        ) {
           throw new CustomProviderError(
             'No content in response',
             ErrorCodes.NO_RESPONSE_CONTENT,
@@ -475,6 +502,7 @@ export function createOpenAICompatibleProvider(providerConfig) {
             response_time_ms: responseTime,
             finish_reason: finishReason,
             provider: providerName.toLowerCase(),
+            ...(hasReasoningContent && { reasoning_content: reasoningContent }),
           },
         };
 
@@ -521,6 +549,13 @@ export function createOpenAICompatibleProvider(providerConfig) {
       let lastUsage = null;
       let finishReason = null;
       let finalModel = resolvedModel;
+      // Extra metadata accumulated from per-chunk hooks (reasoning_details,
+      // annotations, usage.cost/cost_details, upstream provider, request id) that
+      // the streaming path's synthetic transformResponse cannot see.
+      const streamMetadataPatch = {};
+      // Persistent per-stream scratch object handed to transformStreamChunk so a
+      // provider can accumulate state (e.g. concatenated reasoning) across chunks.
+      const streamState = { modelConfig, resolvedModel };
 
       try {
         // Check if already aborted before starting
@@ -553,8 +588,45 @@ export function createOpenAICompatibleProvider(providerConfig) {
               );
               break;
             }
+
+            // Optional per-chunk hook: yields extra normalized events, patches
+            // final metadata, can suppress default delta handling, and can
+            // terminate the stream as failed on a fatal in-band error.
+            let suppressDefault = false;
+            if (transformStreamChunk) {
+              const hookResult =
+                transformStreamChunk(chunk, streamState) || {};
+              const {
+                events = [],
+                metadataPatch = null,
+                suppressDefault: hookSuppress = false,
+                terminalError = null,
+              } = hookResult;
+              for (const extraEvent of events) {
+                yield extraEvent;
+              }
+              if (metadataPatch) {
+                Object.assign(streamMetadataPatch, metadataPatch);
+              }
+              if (terminalError) {
+                // Emit exactly one failure event and stop WITHOUT a later end
+                // event, leaving already-emitted deltas intact.
+                yield {
+                  type: 'error',
+                  error: {
+                    message: terminalError.message || 'Stream terminated',
+                    code: terminalError.code || 'STREAMING_ERROR',
+                    recoverable: false,
+                  },
+                  timestamp: new Date().toISOString(),
+                };
+                return;
+              }
+              suppressDefault = hookSuppress;
+            }
+
             const choice = chunk.choices?.[0];
-            if (choice) {
+            if (!suppressDefault && choice) {
               const content = choice.delta?.content || '';
 
               // Handle regular content
@@ -567,18 +639,22 @@ export function createOpenAICompatibleProvider(providerConfig) {
                 };
               }
 
-              // Handle reasoning/thinking content if supported
-              if (choice.delta?.reasoning && modelConfig.supportsReasoning) {
+              // Handle reasoning/thinking content if supported. DeepSeek and
+              // OpenRouter expose streamed reasoning as delta.reasoning_content.
+              if (
+                choice.delta?.reasoning_content &&
+                modelConfig.supportsReasoning
+              ) {
                 yield {
                   type: 'thinking',
-                  content: choice.delta.reasoning,
+                  content: choice.delta.reasoning_content,
                   timestamp: new Date().toISOString(),
                 };
               }
+            }
 
-              if (choice.finish_reason) {
-                finishReason = choice.finish_reason;
-              }
+            if (choice?.finish_reason) {
+              finishReason = choice.finish_reason;
             }
 
             // Handle usage information (typically in final chunk)
@@ -653,6 +729,15 @@ export function createOpenAICompatibleProvider(providerConfig) {
           finalResult = await transformResponse(finalResult, mockRawResponse);
         }
 
+        // Merge any per-chunk metadata patches last so hook-supplied fields
+        // (reasoning_details, annotations, cost, upstream provider) win.
+        if (Object.keys(streamMetadataPatch).length > 0) {
+          finalResult.metadata = {
+            ...finalResult.metadata,
+            ...streamMetadataPatch,
+          };
+        }
+
         // Yield end event with final metadata
         yield {
           type: 'end',