converse-mcp-server 2.29.2 → 3.0.1

package/src/tools/modes/roundtable.js

@@ -0,0 +1,495 @@
+/**
+ * Roundtable Mode Engine
+ *
+ * Turn-based multi-model round-table. Models respond SEQUENTIALLY in the order
+ * given; each model sees the full running transcript (prior laps + earlier turns
+ * in the current lap) and builds on it. One tool call runs exactly one lap (one
+ * turn per model); the caller drives more laps by passing back the continuation_id.
+ *
+ * This is the sequential counterpart to the parallel engine. It is an execution
+ * core: it resolves the turn plan, runs the lap loop, and RETURNS the lap data
+ * (turns, transcript, counts). Persistence, export, and MCP-response construction
+ * live in the unified chat tool's shared shell.
+ *
+ * CRITICAL provider constraint: SDK providers (codex, claude, copilot) reduce the
+ * message array to ONLY the last `user` message. Therefore each turn's entire
+ * context (prior-lap transcript + lap prompt + same-lap turns + framing) is packed
+ * into a SINGLE self-contained final user message ("turn packet"). Do not spread
+ * turn context across multiple messages.
+ */
+
+import { debugLog } from '../../utils/console.js';
+import { acquireProviderStream } from './streamShared.js';
+import {
+  getDefaultModelForProvider,
+  getProviderUnavailableMessage,
+  getAvailableProviders,
+  resolveModelSpec,
+} from '../../utils/modelRouting.js';
+
+/**
+ * Render a stored transcript (from prior laps or a prior chat/consensus thread)
+ * into labeled text that can be embedded in the next turn's packet. Stored state
+ * pairs user (prompt) and assistant (response) messages; we re-render those as
+ * readable context so last-user-only SDK providers still see the history (and so
+ * a provider does not mistake prior multi-speaker transcript for its own previous
+ * output). Also used by the parallel engine's shell to pack prior history into a
+ * resumed chat/consensus turn.
+ * @param {Array} storedMessages - Stored messages from a prior conversation state
+ * @returns {string} Labeled prior-transcript text ('' for a new conversation)
+ */
+export function renderStoredTranscriptToText(storedMessages = []) {
+  if (!Array.isArray(storedMessages) || storedMessages.length === 0) {
+    return '';
+  }
+
+  const blocks = [];
+  let lapNumber = 0;
+  let pendingPrompt = null;
+
+  const toText = (content) => {
+    if (typeof content === 'string') {
+      return content;
+    }
+    if (Array.isArray(content)) {
+      // Complex content array (files/images + text) — extract text parts only
+      return content
+        .filter((part) => part && part.type === 'text' && part.text)
+        .map((part) => part.text)
+        .join('\n');
+    }
+    return '';
+  };
+
+  for (const message of storedMessages) {
+    if (!message || message.role === 'system') {
+      continue;
+    }
+    if (message.role === 'user') {
+      pendingPrompt = toText(message.content);
+    } else if (message.role === 'assistant') {
+      lapNumber += 1;
+      const promptText = pendingPrompt ? `${pendingPrompt}\n\n` : '';
+      const assistantText = toText(message.content);
+      blocks.push(
+        `## Earlier in this round-table (lap ${lapNumber}):\n${promptText}${assistantText}`,
+      );
+      pendingPrompt = null;
+    }
+  }
+
+  return blocks.join('\n\n');
+}
+
+/**
+ * Build the per-turn framing text for the model at position `i`.
+ * @param {object} params
+ * @returns {string} Framing text appended to the turn packet
+ */
+function buildFramingText({ i, models }) {
+  const total = models.length;
+  const selfModel = models[i];
+  const prevModel = i > 0 ? models[i - 1] : null;
+  const nextModel = i < total - 1 ? models[i + 1] : null;
+
+  const order = models.join(', ');
+  const prevText = prevModel || 'no one (you open the round)';
+  const nextText = nextModel || 'no one (you close this round)';
+  const handoffText = nextModel
+    ? `Your response will be passed to the next participant (${nextModel}).`
+    : 'Your response will be returned to the user, as you are the last participant this round.';
+
+  const lines = [
+    `You are participant "${selfModel}" in a multi-model round-table conversation.`,
+    `Participants, in speaking order: ${order}.`,
+    `You are speaking in position ${i + 1} of ${total}, after ${prevText}, before ${nextText}.`,
+    'The original topic/prompt for this round is shown above, followed by any responses already given this round.',
+    'Respond to the whole conversation so far — build on, challenge, or refine what others have said; do not merely repeat them.',
+    handoffText,
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Build the single self-contained turn packet TEXT for the model at position `i`.
+ * Order: prior-transcript section, lap prompt, same-lap turns, framing.
+ * This is the LAST user message — the only thing last-user-only SDK providers see.
+ * @param {object} params
+ * @returns {string} Turn packet text
+ */
+function buildTurnPacket({ priorTranscriptText, prompt, sameLapTurns, i, models }) {
+  const parts = [];
+
+  if (priorTranscriptText && priorTranscriptText.trim()) {
+    parts.push(priorTranscriptText.trim());
+  }
+
+  parts.push(`Original topic for this round:\n${prompt}`);
+
+  // Same-lap turns from models 0..i-1 (omitted for the opener, i=0)
+  if (i > 0 && sameLapTurns.length > 0) {
+    const turnBlocks = sameLapTurns.map((turn) => {
+      if (turn.status === 'success') {
+        return `### ${turn.model} said:\n${turn.response}`;
+      }
+      return `### ${turn.model} did not respond (error: ${turn.error})`;
+    });
+    parts.push(turnBlocks.join('\n\n'));
+  }
+
+  parts.push(buildFramingText({ i, models }));
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Format the full lap transcript for storage/display.
+ * @param {Array} lapTurns - Turns from the current lap
+ * @returns {string} Formatted transcript
+ */
+export function formatLapTranscript(lapTurns) {
+  let content = '';
+  let successful = 0;
+
+  lapTurns.forEach((turn, index) => {
+    if (turn.status === 'success') {
+      successful += 1;
+      content += `### ${turn.model} (turn ${index + 1}):\n${turn.response}\n\n---\n\n`;
+    } else {
+      content += `### ${turn.model} (turn ${index + 1}, did not respond):\nError: ${turn.error}\n\n---\n\n`;
+    }
+  });
+
+  content += `\n**Summary:** Conversation lap completed with ${successful}/${lapTurns.length} successful turns.`;
+  return content;
+}
+
+/**
+ * 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).
+ * @param {Array<string>} models - Ordered model list
+ * @param {object} providers - Provider instances
+ * @param {object} config - Configuration
+ * @param {boolean} hasImages - Whether the request includes images
+ * @returns {Array<object>} Ordered turn plan entries
+ */
+export function resolveTurnPlan(models, providers, config, hasImages = false) {
+  // Single "auto" expands to the first available provider's default model only
+  // (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, {
+      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'];
+  }
+
+  return modelsToProcess.map((modelName) => {
+    if (!modelName || typeof modelName !== 'string') {
+      return {
+        model: modelName || 'unknown',
+        provider: null,
+        providerInstance: null,
+        resolvedModel: null,
+        preFailReason: 'Invalid model specification',
+      };
+    }
+
+    const { providerName, provider, resolvedModel, status, options } =
+      resolveModelSpec(modelName, providers, config);
+
+    if (status === 'not_found') {
+      return {
+        model: modelName,
+        provider: providerName,
+        providerInstance: null,
+        resolvedModel,
+        preFailReason: `Provider not found: ${providerName}`,
+      };
+    }
+
+    if (status === 'unavailable') {
+      return {
+        model: modelName,
+        provider: providerName,
+        providerInstance: null,
+        resolvedModel,
+        preFailReason: getProviderUnavailableMessage(providerName),
+      };
+    }
+
+    return {
+      model: modelName,
+      provider: providerName,
+      providerInstance: provider,
+      resolvedModel,
+      resolveOptions: options,
+      preFailReason: null,
+    };
+  });
+}
+
+/**
+ * Build the final user message content for a turn. Files/images are attached to
+ * THIS message so multimodal providers see them, with the packet text appended.
+ * @returns {string|Array} User message content
+ */
+function buildTurnUserContent(packetText, contextMessage) {
+  if (contextMessage && contextMessage.content) {
+    return [...contextMessage.content, { type: 'text', text: packetText }];
+  }
+  return packetText;
+}
+
+/**
+ * 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 }
+ */
+async function executeTurn(
+  plan,
+  messages,
+  options,
+  context,
+  streamNormalizer,
+  turnIndex,
+) {
+  // `options.signal` is the active signal for both sync (request signal) and
+  // async (job context signal) paths.
+  const activeSignal = options.signal;
+  try {
+    if (activeSignal?.aborted) {
+      throw new Error('Roundtable execution was cancelled');
+    }
+
+    // Synchronous path (no job context): plain invoke.
+    if (!context) {
+      const response = await plan.providerInstance.invoke(messages, options);
+      return {
+        model: plan.model,
+        provider: plan.provider,
+        status: 'success',
+        response: response.content,
+        metadata: response.metadata || {},
+      };
+    }
+
+    // Async path: stream and surface progress.
+    const { stream, response: acquiredResponse } = await acquireProviderStream(
+      plan.providerInstance,
+      messages,
+      options,
+    );
+    let response = acquiredResponse;
+
+    if (stream) {
+      const normalizedStream = streamNormalizer.normalize(plan.provider, stream, {
+        provider: plan.provider,
+        model: options.model,
+        requestId: `${context.jobId}-turn-${turnIndex}`,
+      });
+
+      let accumulatedContent = '';
+      let finalUsage = null;
+      let finalMetadata = {};
+
+      for await (const event of normalizedStream) {
+        if (context.signal?.aborted) {
+          throw new Error('Roundtable execution was cancelled');
+        }
+
+        switch (event.type) {
+        case 'delta':
+          accumulatedContent += event.data.textDelta;
+          break;
+        case 'usage':
+          finalUsage = event.data.usage;
+          break;
+        case 'end':
+          accumulatedContent = event.data.content || accumulatedContent;
+          finalUsage = event.data.usage || finalUsage;
+          finalMetadata = event.data.metadata || finalMetadata;
+          break;
+        case 'error':
+          throw new Error(`Streaming error: ${event.data.error.message}`);
+        }
+      }
+
+      response = {
+        content: accumulatedContent,
+        metadata: { ...finalMetadata, usage: finalUsage, streaming: true },
+      };
+    }
+
+    if (!stream && !response) {
+      response = await plan.providerInstance.invoke(messages, options);
+    }
+
+    return {
+      model: plan.model,
+      provider: plan.provider,
+      status: 'success',
+      response: response.content,
+      metadata: response.metadata || {},
+    };
+  } catch (error) {
+    // Cancellation must abort the whole lap, not be demoted to a failed turn.
+    // Rethrow so it propagates to the caller (sync shell or job runner).
+    if (activeSignal?.aborted || error.name === 'AbortError') {
+      throw error;
+    }
+    return {
+      model: plan.model,
+      provider: plan.provider,
+      status: 'failed',
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Run one roundtable lap: one turn per model, in order, each seeing the full
+ * running transcript. Returns the lap data for the shell to persist/format.
+ *
+ * @param {object} params
+ * @param {Array<string>} params.models - Ordered model list
+ * @param {string} params.prompt - Lap prompt
+ * @param {Array} params.priorHistory - Loaded stored messages (may include a leading system msg)
+ * @param {object|null} params.contextMessage - Files/images context message
+ * @param {string} params.systemPrompt - System prompt for the roundtable mode
+ * @param {object} params.providers - Provider instances
+ * @param {object} params.config - Configuration
+ * @param {AbortSignal} [params.signal] - Sync-path abort signal
+ * @param {string} params.reasoning_effort - Reasoning depth
+ * @param {boolean} params.hasImages - Whether the request includes images
+ * @param {object|null} [params.context] - Job context (async) or null (sync)
+ * @param {object} [params.providerStreamNormalizer] - Stream normalizer (async)
+ * @returns {Promise<object>} { lapTurns, transcript, turnsSuccessful, turnsFailed, lapUserMessage }
+ */
+export async function runRoundtableLap({
+  models,
+  prompt,
+  priorHistory,
+  contextMessage,
+  systemPrompt,
+  providers,
+  config,
+  signal,
+  reasoning_effort,
+  hasImages,
+  context = null,
+  providerStreamNormalizer,
+}) {
+  const priorTranscriptText = renderStoredTranscriptToText(priorHistory);
+  const turnPlan = resolveTurnPlan(models, providers, config, hasImages);
+  const activeSignal = context ? context.signal : signal;
+
+  if (context) {
+    await context.updateJob({
+      models_list: models.join(', '),
+      roundtable_progress: `0/${turnPlan.length}`,
+      total_turns: turnPlan.length,
+      completed_turns: 0,
+    });
+  }
+
+  const lapTurns = [];
+
+  for (let i = 0; i < turnPlan.length; i++) {
+    if (activeSignal?.aborted) {
+      throw new Error('Roundtable execution was cancelled');
+    }
+
+    const plan = turnPlan[i];
+
+    if (plan.preFailReason) {
+      lapTurns.push({
+        model: plan.model,
+        provider: plan.provider,
+        status: 'failed',
+        error: plan.preFailReason,
+        position: i,
+      });
+    } else {
+      const packetText = buildTurnPacket({
+        priorTranscriptText,
+        prompt,
+        sameLapTurns: lapTurns,
+        i,
+        models,
+      });
+
+      const finalUserContent = buildTurnUserContent(packetText, contextMessage);
+
+      const messages = [
+        { role: 'system', content: systemPrompt },
+        { 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,
+      );
+
+      lapTurns.push({ ...turnResult, position: i });
+    }
+
+    if (context) {
+      // Report per-turn progress with the running transcript. Use flat keys (not
+      // a `progress` object) — asyncJobStore.update() treats the reserved
+      // `progress` key as a numeric 0..1 value. Numeric overall progress is
+      // supplied separately as a fraction.
+      await context.updateJob({
+        roundtable_progress: `${i + 1}/${turnPlan.length}`,
+        accumulated_content: formatLapTranscript(lapTurns),
+        progress: (i + 1) / turnPlan.length,
+        total_turns: turnPlan.length,
+        completed_turns: i + 1,
+        current_model: plan.model,
+      });
+    }
+  }
+
+  const turnsSuccessful = lapTurns.filter((t) => t.status === 'success').length;
+  const turnsFailed = lapTurns.length - turnsSuccessful;
+  const transcript = formatLapTranscript(lapTurns);
+
+  const lapUserMessage = {
+    role: 'user',
+    content: buildTurnUserContent(prompt, contextMessage),
+  };
+
+  debugLog(
+    `[Roundtable] Lap completed: ${turnsSuccessful}/${lapTurns.length} turns succeeded`,
+  );
+
+  return {
+    lapTurns,
+    transcript,
+    turnsSuccessful,
+    turnsFailed,
+    lapUserMessage,
+  };
+}

package/src/tools/modes/streamShared.js

@@ -0,0 +1,31 @@
+/**
+ * Shared streaming helper for the mode engines.
+ *
+ * Both the parallel and roundtable engines acquire a stream from a provider the
+ * same way: providers with a native `stream(messages, options)` method return an
+ * async iterator directly; SDK providers (copilot, codex, claude, gemini-cli)
+ * instead stream via `invoke(..., { stream: true })`, which may yield an async
+ * iterator or, when streaming is unavailable, a plain response object.
+ */
+
+/**
+ * Acquire a stream (or a plain response) from a provider for the async path.
+ * @param {object} providerInstance - Provider implementation
+ * @param {Array} messages - Message array
+ * @param {object} options - Invocation options
+ * @returns {Promise<{ stream: (AsyncIterable|null), response: (object|undefined) }>}
+ */
+export async function acquireProviderStream(providerInstance, messages, options) {
+  if (providerInstance.stream && typeof providerInstance.stream === 'function') {
+    return { stream: providerInstance.stream(messages, options), response: undefined };
+  }
+  // SDK providers (copilot, codex, claude, gemini-cli) stream via invoke
+  const streamResult = await providerInstance.invoke(messages, {
+    ...options,
+    stream: true,
+  });
+  if (streamResult && typeof streamResult[Symbol.asyncIterator] === 'function') {
+    return { stream: streamResult, response: undefined };
+  }
+  return { stream: null, response: streamResult };
+}

package/src/utils/contextProcessor.js

@@ -265,35 +265,10 @@ export async function processMultipleFiles(filePaths, options = {}) {
 }
 
 /**
- * Web search context integration (placeholder)
- * @param {string} query - Search query
- * @param {object} options - Search options
- * @returns {Promise<object>} Web search results for context
- */
-export async function processWebSearchContext(query, options = {}) {
-  // Placeholder implementation - can be enhanced with actual web search API
-  return {
-    type: 'web_search',
-    query,
-    results: [],
-    error: null,
-    timestamp: new Date().toISOString(),
-    // Placeholder: Future implementation could integrate with:
-    // - Google Search API
-    // - Bing Search API
-    // - DuckDuckGo API
-    // - Custom search engines
-    placeholder: true,
-    message: 'Web search integration placeholder - not yet implemented',
-  };
-}
-
-/**
- * Unified context processor - handles all context types
+ * Unified context processor - handles files and images
  * @param {object} contextRequest - Context processing request
  * @param {string[]} contextRequest.files - Array of file paths
  * @param {string[]} contextRequest.images - Array of image paths (for explicit image processing)
- * @param {string} contextRequest.webSearch - Web search query
  * @param {object} options - Processing options
  * @returns {Promise<object>} Unified context result
  */
@@ -301,7 +276,6 @@ export async function processUnifiedContext(contextRequest, options = {}) {
   const result = {
     files: [],
     images: [],
-    webSearch: null,
     errors: [],
     timestamp: new Date().toISOString(),
   };
@@ -319,17 +293,6 @@ export async function processUnifiedContext(contextRequest, options = {}) {
         imageProcessingMode: true, // Placeholder for future image-specific processing
       });
     }
-
-    // Process web search if provided
-    if (
-      contextRequest.webSearch &&
-      typeof contextRequest.webSearch === 'string'
-    ) {
-      result.webSearch = await processWebSearchContext(
-        contextRequest.webSearch,
-        options,
-      );
-    }
   } catch (error) {
     result.errors.push({
       type: 'unified_processing_error',

package/src/utils/conversationExporter.js

@@ -143,9 +143,7 @@ function extractMessageContent(message) {
 function generateMetadata(conversationState, totalTurns, params) {
   const metadata = {
     continuation_id: params.continuation_id,
-    model: params.model || 'auto',
-    provider: conversationState.provider,
-    temperature: params.temperature || 0.5,
+    mode: params.mode || conversationState.mode || 'chat',
     total_turns: totalTurns,
     created_at: conversationState.createdAt
       ? new Date(conversationState.createdAt).toISOString()
@@ -156,15 +154,12 @@ function generateMetadata(conversationState, totalTurns, params) {
   };
 
   // Add optional parameters if present
+  if (params.models && params.models.length > 0) {
+    metadata.models = params.models;
+  }
   if (params.reasoning_effort) {
     metadata.reasoning_effort = params.reasoning_effort;
   }
-  if (params.verbosity) {
-    metadata.verbosity = params.verbosity;
-  }
-  if (params.use_websearch !== undefined) {
-    metadata.use_websearch = params.use_websearch;
-  }
   if (params.files && params.files.length > 0) {
     metadata.files = params.files;
   }
@@ -174,13 +169,6 @@ function generateMetadata(conversationState, totalTurns, params) {
       img.startsWith('data:') ? '[base64 image]' : img,
     );
   }
-  // Consensus-specific metadata
-  if (params.models) {
-    metadata.models = params.models;
-  }
-  if (params.enable_cross_feedback !== undefined) {
-    metadata.enable_cross_feedback = params.enable_cross_feedback;
-  }
 
   return metadata;
 }
@@ -195,15 +183,11 @@ export async function exportConversation(conversationState, options = {}) {
   const {
     clientCwd,
     continuation_id,
-    model,
-    temperature,
+    mode,
     reasoning_effort,
-    verbosity,
-    use_websearch,
     files,
     images,
     models,
-    enable_cross_feedback,
   } = options;
 
   if (!continuation_id) {
@@ -253,15 +237,11 @@ export async function exportConversation(conversationState, options = {}) {
     // 5. Always update metadata atomically
     const metadata = generateMetadata(conversationState, turns.length, {
       continuation_id,
-      model,
-      temperature,
+      mode,
       reasoning_effort,
-      verbosity,
-      use_websearch,
       files,
       images,
       models,
-      enable_cross_feedback,
     });
 
     const metadataPath = path.join(exportDir, 'metadata.json');