converse-mcp-server 2.29.2 → 3.0.1

package/src/tools/chat.js

@@ -1,95 +1,140 @@
 /**
- * Chat Tool
+ * Chat Tool (unified)
  *
- * Single-provider conversational AI with context and continuation support.
- * Handles context processing, provider calls, and state management.
+ * A single MCP tool with three execution modes:
+ *   - `chat`       : 1..N models invoked in parallel; each responds independently.
+ *   - `consensus`  : ≥2 models in parallel, then a cross-feedback refinement phase.
+ *   - `roundtable` : models respond sequentially, each seeing the full transcript.
+ *
+ * This module is the shared shell: it validates arguments, loads/normalizes
+ * continuation history, builds file/image context, dispatches to the parallel or
+ * roundtable execution engine, and owns persistence, export, token-limiting, and
+ * MCP-response construction. The engines (`modes/parallel.js`, `modes/roundtable.js`)
+ * only resolve/invoke and return invocation data.
  */
 
-import { createToolResponse, createToolError } from './index.js';
-import {
-  processUnifiedContext,
-  createFileContext,
-} from '../utils/contextProcessor.js';
+import { createToolResponse, createToolError, formatFailureDetails } from './index.js';
+import { createFileContext } from '../utils/contextProcessor.js';
 import {
   generateContinuationId,
-  addMessageToHistory,
   isValidContinuationId,
 } from '../continuationStore.js';
 import { isSafeIdSegment } from '../utils/idValidation.js';
-import { debugLog, debugError } from '../utils/console.js';
+import { debugError } from '../utils/console.js';
 import { createLogger } from '../utils/logger.js';
-import { CHAT_PROMPT } from '../systemPrompts.js';
+import { getSystemPromptForMode } from '../systemPrompts.js';
 import { applyTokenLimit, getTokenLimit } from '../utils/tokenLimiter.js';
 import { validateAllPaths } from '../utils/fileValidator.js';
 import { SummarizationService } from '../services/summarizationService.js';
 import { exportConversation } from '../utils/conversationExporter.js';
-import { isRecoverableError, retryWithBackoff } from '../utils/errorHandler.js';
 import {
-  providerSupportsImages,
+  getDefaultModelForProvider,
   getProviderUnavailableMessage,
+  getAvailableProviders,
+  resolveModelSpec,
 } from '../utils/modelRouting.js';
+import {
+  runChatMode,
+  runConsensusMode,
+  getProviderRetryOptions,
+} from './modes/parallel.js';
+import {
+  runRoundtableLap,
+  renderStoredTranscriptToText,
+} from './modes/roundtable.js';
 
 const logger = createLogger('chat');
 
+const VALID_MODES = ['chat', 'consensus', 'roundtable'];
+
+// SDK providers that consume ONLY the last user message. On a resumed thread in
+// chat/consensus modes, prior history must be packed into that final message for
+// these providers (codex is exempt in chat mode when it can reuse its own thread).
+const LAST_USER_ONLY = new Set(['codex', 'claude', 'copilot']);
+
 /**
- * Chat tool implementation
+ * Unified chat tool implementation.
  * @param {object} args - Tool arguments
- * @param {object} dependencies - Injected dependencies (config, providers, continuationStore)
+ * @param {object} dependencies - Injected dependencies
  * @returns {object} MCP tool response
  */
 export async function chatTool(args, dependencies) {
   try {
-    const {
-      config,
-      providers,
-      continuationStore,
-      contextProcessor,
-      jobRunner,
-      providerStreamNormalizer,
-      signal,
-    } = dependencies;
+    const { config, providers, continuationStore, jobRunner, providerStreamNormalizer } =
+      dependencies;
 
-    // Validate required arguments
-    if (!args.prompt || typeof args.prompt !== 'string') {
+    if (!args.prompt || typeof args.prompt !== 'string' || !args.prompt.trim()) {
       return createToolError('Prompt is required and must be a string');
     }
 
-    // Extract and validate arguments
+    // The router applies no JSON-Schema defaults, so apply them in code.
+    const mode = args.mode ?? 'chat';
+    const models = args.models ?? ['auto'];
+    const reasoning_effort = args.reasoning_effort ?? 'medium';
     const {
       prompt,
-      model = 'auto',
       files = [],
-      continuation_id,
-      temperature = 0.5,
-      use_websearch = false,
       images = [],
-      reasoning_effort = 'medium',
-      verbosity = 'medium',
-      async = false,
+      continuation_id,
+      async: isAsync = false,
       export: shouldExport = false,
     } = args;
 
-    // Handle async execution mode
-    if (async) {
-      // Validate async dependencies are available
+    if (!VALID_MODES.includes(mode)) {
+      return createToolError(
+        `Invalid mode "${mode}". Valid modes are: ${VALID_MODES.join(', ')}.`,
+      );
+    }
+
+    const modelsError = validateModels(models, mode);
+    if (modelsError) {
+      return createToolError(modelsError);
+    }
+
+    // Consensus needs ≥2 *resolved* (available) models, checked AFTER auto
+    // expansion so the default ["auto"] is valid.
+    if (mode === 'consensus') {
+      const { resolved } = resolveConsensusCallPlans(
+        models,
+        providers,
+        config,
+        images,
+      );
+      if (resolved.length < 2) {
+        return createToolError(
+          'Consensus mode requires at least 2 available models. ' +
+            'Provide 2+ models (or "auto" when 2+ providers are configured), ' +
+            'or use mode "chat" for a single model.',
+        );
+      }
+    }
+
+    const normalizedArgs = {
+      prompt,
+      mode,
+      models,
+      reasoning_effort,
+      files,
+      images,
+      continuation_id,
+      export: shouldExport,
+    };
+
+    if (isAsync) {
       if (!jobRunner || !providerStreamNormalizer) {
         return createToolError(
           'Async execution not available - missing async dependencies',
         );
       }
 
-      // Validate custom continuation ID for async safety (used as filesystem path segment)
       if (continuation_id && !isSafeIdSegment(continuation_id)) {
         return createToolError(
           `Invalid continuation_id for async mode: "${continuation_id}". Async IDs must contain only letters, numbers, hyphens, and underscores (max 128 chars).`,
         );
       }
 
-      // Generate or use existing continuation ID for the conversation
-      const conversationContinuationId =
-        continuation_id || generateContinuationId();
+      const jobContinuationId = continuation_id || generateContinuationId();
 
-      // Determine if this is a custom ID (non-standard format AND not found in store)
       let isCustomId = false;
       if (continuation_id && !isValidContinuationId(continuation_id)) {
         try {
@@ -100,77 +145,46 @@ export async function chatTool(args, dependencies) {
         }
       }
 
-      // Get provider and model info for the job
-      const providerName = mapModelToProvider(args.model || 'auto', providers);
-      const resolvedModel =
-        providers[providerName]?.resolveModel?.(args.model) ||
-        args.model ||
-        'auto';
-
-      // Generate title early for initial response
+      const modelsList = models.join(', ');
       const summarizationService = new SummarizationService(providers, config);
       let title = null;
       try {
         title = await summarizationService.generateTitle(prompt);
-        debugLog(`Chat: Generated title for initial response - "${title}"`);
       } catch (error) {
-        debugError(
-          'Chat: Failed to generate title for initial response',
-          error,
-        );
+        debugError('Chat: Failed to generate title for initial response', error);
         title = prompt.substring(0, 50);
       }
 
       try {
-        // Submit background job using continuation_id as the job identifier
-        const jobId = await jobRunner.submit(
+        await jobRunner.submit(
           {
             tool: 'chat',
-            sessionId: 'local-user', // Use standard session ID
+            mode,
+            sessionId: jobContinuationId,
             options: {
-              ...args,
-              jobId: conversationContinuationId, // Use continuation_id as job ID
-              continuation_id: conversationContinuationId, // Pass the conversation continuation ID
-              provider: providerName, // Add provider info for status display
-              model: resolvedModel, // Add resolved model info for status display
-              title, // Pass the generated title
+              ...normalizedArgs,
+              jobId: jobContinuationId,
+              continuation_id: jobContinuationId,
+              mode,
+              models_list: modelsList,
+              title,
             },
           },
           async (context) => {
-            // Execute chat in background using stream normalizer
-            return await executeChatWithStreaming(
-              args,
-              {
-                ...dependencies,
-                continuationId: conversationContinuationId,
-                isCustomId,
-                title, // Pass title to execution context
-              },
+            return await runAsyncJob(
+              { ...normalizedArgs, continuation_id: jobContinuationId },
+              { ...dependencies, isCustomId, title },
               context,
             );
           },
         );
 
-        // Format initial response like check_status output
-        const startTime = new Date()
-          .toLocaleString('en-GB', {
-            day: '2-digit',
-            month: '2-digit',
-            year: 'numeric',
-            hour: '2-digit',
-            minute: '2-digit',
-            second: '2-digit',
-            hour12: false,
-          })
-          .replace(',', '');
-
-        const statusLine = `⏳ SUBMITTED | CHAT | ${conversationContinuationId} | 1/1 | Started: ${startTime} | "${title || 'Processing...'}" | ${providerName}/${resolvedModel}`;
-
-        // Return formatted response with status line and continuation_id
+        const statusLine = `⏳ SUBMITTED | ${mode.toUpperCase()} | ${jobContinuationId} | 1/1 | Started: ${formatStartTime()} | "${title || 'Processing...'}" | ${modelsList}`;
+
         return createToolResponse({
-          content: `${statusLine}\ncontinuation_id: ${conversationContinuationId}`,
+          content: `${statusLine}\ncontinuation_id: ${jobContinuationId}`,
           continuation: {
-            id: conversationContinuationId, // Use continuation_id as the primary ID
+            id: jobContinuationId,
             status: 'processing',
             ...(isCustomId && { custom_id: true }),
           },
@@ -182,1062 +196,1010 @@ export async function chatTool(args, dependencies) {
       }
     }
 
-    let conversationHistory = [];
-    let continuationId = continuation_id;
-    let isCustomId = false;
-
-    // Load existing conversation if continuation_id provided
-    if (continuationId) {
-      try {
-        const existingState = await continuationStore.get(continuationId);
-        if (existingState) {
-          conversationHistory = existingState.messages || [];
-        } else {
-          // Preserve user-provided ID and start fresh conversation
-          isCustomId = !isValidContinuationId(continuationId);
-        }
-      } catch (error) {
-        logger.error('Error loading conversation', { error });
-        // Preserve user-provided ID on error
-        isCustomId = !isValidContinuationId(continuationId);
-      }
-    } else {
-      // Generate new continuation ID for new conversation
-      continuationId = generateContinuationId();
-    }
-
-    // Validate file paths before processing
-    if (files.length > 0 || images.length > 0) {
-      const validation = await validateAllPaths(
-        { files, images },
-        { clientCwd: config.server?.client_cwd },
-      );
-      if (!validation.valid) {
-        logger.error('File validation failed', { errors: validation.errors });
-        return validation.errorResponse;
-      }
+    // Synchronous path
+    const pipeline = await runUnifiedChat(normalizedArgs, dependencies, null);
+    if (pipeline.error) {
+      return pipeline.error;
     }
-
-    // Process context (files, images, web search)
-    let contextMessage = null;
-    if (files.length > 0 || images.length > 0 || use_websearch) {
-      try {
-        const contextRequest = {
-          files: Array.isArray(files) ? files : [],
-          images: Array.isArray(images) ? images : [],
-          webSearch: use_websearch ? prompt : null,
-        };
-
-        const contextResult = await contextProcessor.processUnifiedContext(
-          contextRequest,
-          {
-            enforceSecurityCheck: false, // Allow files from any location
-            skipSecurityCheck: true, // Legacy flag for backward compatibility
-            clientCwd: config.server?.client_cwd, // Use auto-detected client working directory
-          },
-        );
-
-        // Create context message from files and images
-        const allProcessedFiles = [
-          ...contextResult.files,
-          ...contextResult.images,
-        ];
-        if (allProcessedFiles.length > 0) {
-          contextMessage = createFileContext(allProcessedFiles, {
-            includeMetadata: true,
-            includeErrors: true,
-          });
-        }
-
-        // Add web search results if available (placeholder for now)
-        if (contextResult.webSearch && !contextResult.webSearch.placeholder) {
-          // Future implementation: add web search results to context
-          logger.debug('Web search results available but not yet implemented');
-        }
-      } catch (error) {
-        logger.error('Error processing context', { error });
-        // Continue without context if processing fails
-      }
-    }
-
-    // Build message array for provider
-    const messages = [];
-
-    // Add system prompt only if not already in conversation history
-    if (
-      conversationHistory.length === 0 ||
-      conversationHistory[0].role !== 'system'
-    ) {
-      messages.push({
-        role: 'system',
-        content: CHAT_PROMPT,
-      });
+    return buildSyncResponse(pipeline, config);
+  } catch (error) {
+    if (dependencies?.signal?.aborted || error.name === 'AbortError') {
+      const cancelledMode = args?.mode ?? 'chat';
+      const label = cancelledMode.charAt(0).toUpperCase() + cancelledMode.slice(1);
+      logger.debug('Chat tool cancelled by client');
+      return createToolError(`${label} request cancelled`);
     }
+    logger.error('Chat tool error', { error });
+    return createToolError('Chat tool failed', error);
+  }
+}
 
-    // Add conversation history
-    messages.push(...conversationHistory);
-
-    // Add user prompt with context
-    const userMessage = {
-      role: 'user',
-      content: prompt, // default to simple string content
-    };
-
-    // If we have context (files/images), create complex content array
-    if (contextMessage && contextMessage.content) {
-      // Create complex content array
-      userMessage.content = [
-        ...contextMessage.content, // Include all file/image parts
-        { type: 'text', text: prompt }, // Add the user prompt as text
-      ];
+/**
+ * Validate the models array and (for chat/consensus) reject duplicates.
+ * @returns {string|null} Error message or null when valid
+ */
+function validateModels(models, mode) {
+  if (!Array.isArray(models) || models.length === 0) {
+    return 'Models must be a non-empty array of model names';
+  }
+  for (const entry of models) {
+    if (!entry || typeof entry !== 'string' || !entry.trim()) {
+      return 'Each model must be a non-empty string';
     }
-
-    messages.push(userMessage);
-
-    // Select provider(s)
-    let selectedProvider;
-    let providerName;
-
-    const providerCandidates = [];
-
-    if (model === 'auto') {
-      // Auto-select providers in priority order
-      // Prioritize subscription-based providers (codex, gemini-cli, claude, copilot) over API-key providers
-      const providerOrder = [
-        'codex',
-        'gemini-cli',
-        'claude',
-        'copilot',
-        'openai',
-        'google',
-        'xai',
-        'anthropic',
-        'mistral',
-        'deepseek',
-        'openrouter',
-      ];
-
-      const requestHasImages = Array.isArray(images) && images.length > 0;
-
-      for (const name of providerOrder) {
-        const provider = providers[name];
-        if (provider && provider.isAvailable && provider.isAvailable(config)) {
-          // When the request has images, skip text-only providers (e.g.
-          // gemini-cli, copilot) so auto routing lands on an image-capable one.
-          if (requestHasImages && !providerSupportsImages(provider, name)) {
-            continue;
-          }
-          providerCandidates.push({ name, provider });
-        }
-      }
-
-      if (providerCandidates.length === 0) {
-        return createToolError(
-          'No providers available. Please configure at least one API key.',
-        );
-      }
-    } else {
-      // Use specified provider/model
-      providerName = mapModelToProvider(model, providers);
-      selectedProvider = providers[providerName];
-
-      if (!selectedProvider) {
-        return createToolError(`Provider not found for model: ${model}`);
-      }
-
-      if (!selectedProvider.isAvailable(config)) {
-        return createToolError(getProviderUnavailableMessage(providerName));
+  }
+  if (mode !== 'roundtable') {
+    const seen = new Set();
+    for (const entry of models) {
+      const key = entry.trim().toLowerCase();
+      if (seen.has(key)) {
+        return `Duplicate model "${entry}" is not allowed in mode "${mode}". Duplicate models are only allowed in mode "roundtable".`;
       }
-
-      providerCandidates.push({
-        name: providerName,
-        provider: selectedProvider,
-      });
+      seen.add(key);
     }
+  }
+  return null;
+}
 
-    // Call provider with recovery (retry and, for auto, failover)
-    let response;
-    const startTime = Date.now();
-    let lastError;
-    let resolvedModel;
-
-    for (const candidate of providerCandidates) {
-      providerName = candidate.name;
-      selectedProvider = candidate.provider;
-
-      // Resolve model name and prepare provider options
-      resolvedModel = resolveAutoModel(model, providerName);
-      const providerOptions = {
-        model: resolvedModel,
-        temperature,
-        reasoning_effort,
-        verbosity,
-        use_websearch,
-        signal,
-        config,
-        continuation_id, // Pass for thread resumption
-        continuationStore, // Pass store for state management
-      };
-
-      try {
-        response = await retryWithBackoff(
-          () => selectedProvider.invoke(messages, providerOptions),
-          getProviderRetryOptions(config, providerName),
-        );
-        break;
-      } catch (error) {
-        lastError = error;
-        logger.error('Provider error', {
-          error,
-          data: { provider: providerName },
-        });
-
-        if (
-          model !== 'auto' ||
-          !shouldFailoverToNextProvider(error) ||
-          candidate === providerCandidates[providerCandidates.length - 1]
-        ) {
-          return createToolError(`Provider error: ${error.message}`);
-        }
-      }
-    }
+/**
+ * The async job runner: executes the pipeline with streaming, then generates a
+ * final summary and returns the completion result for the job store.
+ */
+async function runAsyncJob(args, dependencies, context) {
+  const { providers, config, title: passedTitle } = dependencies;
+
+  const pipeline = await runUnifiedChat(args, dependencies, context);
+  if (pipeline.error) {
+    // Validation errors are surfaced eagerly in chatTool; reaching here means a
+    // runtime failure — throw so the job is marked failed.
+    throw new Error(
+      pipeline.errorMessage || 'Chat job failed during execution',
+    );
+  }
 
-    if (!response) {
-      return createToolError(
-        `Provider error: ${(lastError && lastError.message) || 'Unknown error'}`,
+  const summarizationService = new SummarizationService(providers, config);
+  let finalSummary = null;
+  if (pipeline.combinedForSummary && pipeline.combinedForSummary.length > 100) {
+    try {
+      finalSummary = await summarizationService.generateFinalSummary(
+        pipeline.combinedForSummary,
       );
-    }
-    const executionTime = (Date.now() - startTime) / 1000; // Convert to seconds
-
-    // Validate response
-    if (!response || !response.content) {
-      return createToolError('Provider returned invalid response');
-    }
-
-    // Add assistant response to conversation history
-    const assistantMessage = {
-      role: 'assistant',
-      content: response.content,
-    };
-
-    const updatedMessages = [...messages, assistantMessage];
-
-    // Save conversation state (skip on abort to avoid persisting incomplete history)
-    if (!signal?.aborted) {
-      try {
-        const conversationState = {
-          messages: updatedMessages,
-          provider: providerName,
-          model,
-          lastUpdated: Date.now(),
-          // Store Codex thread ID if available (for thread resumption)
-          codexThreadId: response.metadata?.threadId,
-        };
-
-        await continuationStore.set(continuationId, conversationState);
-      } catch (error) {
-        logger.error('Error saving conversation', { error });
-        // Continue even if save fails
+      if (finalSummary) {
+        await context.updateJob({ final_summary: finalSummary });
       }
+    } catch (error) {
+      debugError('Chat: Failed to generate final summary', error);
     }
+  }
 
-    // Export conversation if requested
-    if (shouldExport) {
-      await exportConversation(
-        {
-          messages: updatedMessages,
-          provider: providerName,
-          model,
-          lastUpdated: Date.now(),
-          codexThreadId: response.metadata?.threadId,
-        },
-        {
-          clientCwd: config.server?.client_cwd,
-          continuation_id: continuationId,
-          model,
-          temperature,
-          reasoning_effort,
-          verbosity,
-          use_websearch,
-          files,
-          images,
-        },
-      );
-    }
-
-    // Create unified status line (similar to async status display)
-    const statusLine =
-      config.environment?.nodeEnv !== 'test'
-        ? `✅ COMPLETED | CHAT | ${continuationId} | ${executionTime.toFixed(1)}s elapsed | ${providerName}/${resolvedModel}\n`
-        : '';
-
-    // Always include continuation_id line for clarity
-    const continuationIdLine = `continuation_id: ${continuationId}\n\n`;
-
-    const result = {
-      content: statusLine + continuationIdLine + response.content,
-      continuation: {
-        id: continuationId,
-        provider: providerName,
-        model,
-        messageCount: updatedMessages.filter((msg) => msg.role !== 'system')
-          .length,
-        ...(isCustomId && { custom_id: true }),
-      },
-    };
-
-    // Add metadata if available
-    if (response.metadata) {
-      result.metadata = response.metadata;
-    }
+  return buildAsyncResult(pipeline, passedTitle, finalSummary);
+}
 
-    // Apply token limiting to the final response
-    const tokenLimit = getTokenLimit(config);
-    const resultStr = JSON.stringify(result, null, 2);
-    const limitedResult = applyTokenLimit(resultStr, tokenLimit);
+/**
+ * The shared pipeline: load history, build context, resolve + invoke via the
+ * mode's engine, persist, export. Returns a normalized pipeline result (or an
+ * `{ error }` for path-validation failures).
+ */
+async function runUnifiedChat(args, dependencies, context) {
+  const {
+    config,
+    providers,
+    continuationStore,
+    contextProcessor,
+    providerStreamNormalizer,
+  } = dependencies;
+  const signal = context ? context.signal : dependencies.signal;
+  const { prompt, mode, models, reasoning_effort, files, images, export: shouldExport } = args;
 
-    // Parse the limited result back to object format to preserve structure
-    let finalResult;
+  // Continuation load
+  let continuationId = args.continuation_id;
+  let isCustomId = false;
+  let existingState = null;
+  if (continuationId) {
     try {
-      finalResult = JSON.parse(limitedResult.content);
-    } catch (e) {
-      // Fallback if parsing fails - return original result
-      finalResult = result;
+      existingState = await continuationStore.get(continuationId);
+    } catch (error) {
+      logger.error('Error loading conversation', { error });
     }
-
-    return createToolResponse(finalResult);
-  } catch (error) {
-    if (dependencies?.signal?.aborted || error.name === 'AbortError') {
-      logger.debug('Chat tool cancelled by client');
-      return createToolError('Chat request cancelled');
+    if (!existingState) {
+      isCustomId = !isValidContinuationId(continuationId);
     }
-    logger.error('Chat tool error', { error });
-    return createToolError('Chat tool failed', error);
+  } else {
+    continuationId = generateContinuationId();
   }
-}
 
-/**
- * Map model name to provider name
- * @param {string} model - Model name
- * @returns {string} Provider name
- */
-/**
- * Resolve "auto" model to default model for the provider
- */
-function resolveAutoModel(model, providerName) {
-  if (model.toLowerCase() !== 'auto') {
-    return model;
-  }
+  const priorHistory = existingState?.messages || [];
+  // Strip any stored leading system message so exactly one current-mode system
+  // prompt leads the invoked/persisted history (prevents a cross-mode resume
+  // running the previous mode's prompt).
+  const normalizedHistory =
+    priorHistory.length > 0 && priorHistory[0].role === 'system'
+      ? priorHistory.slice(1)
+      : priorHistory;
 
-  const defaults = {
-    codex: 'codex',
-    'gemini-cli': 'gemini',
-    claude: 'claude',
-    copilot: 'copilot',
-    openai: 'gpt-5',
-    xai: 'grok-4-0709',
-    google: 'gemini-pro',
-    anthropic: 'claude-sonnet-4-20250514',
-    mistral: 'magistral-medium-2506',
-    deepseek: 'deepseek-reasoner',
-    openrouter: 'qwen/qwen3-coder',
-  };
+  // Path validation
+  if (files.length > 0 || images.length > 0) {
+    const validation = await validateAllPaths(
+      { files, images },
+      { clientCwd: config.server?.client_cwd },
+    );
+    if (!validation.valid) {
+      logger.error('File validation failed', { errors: validation.errors });
+      return { error: validation.errorResponse };
+    }
+  }
 
-  return defaults[providerName] || 'gpt-5';
-}
+  const contextMessage = await buildContextMessage(
+    files,
+    images,
+    contextProcessor,
+    config,
+  );
 
-function getProviderRetryOptions(config, providerName) {
-  const nodeEnv = config?.environment?.nodeEnv || process.env.NODE_ENV;
-  const isTest = nodeEnv === 'test';
+  const systemPrompt = getSystemPromptForMode(mode);
+  const systemMessage = { role: 'system', content: systemPrompt };
+  const hasImages = Array.isArray(images) && images.length > 0;
 
-  return {
-    retries: isTest ? 1 : 3,
-    delay: isTest ? 0 : 500,
-    maxDelay: isTest ? 0 : 10000,
-    operation: `provider-invoke:${providerName}`,
+  const common = {
+    mode,
+    models,
+    prompt,
+    reasoning_effort,
+    files,
+    images,
+    continuationId,
+    isCustomId,
+    existingState,
+    normalizedHistory,
+    systemMessage,
+    systemPrompt,
+    contextMessage,
+    hasImages,
+    shouldExport,
+    signal,
+    context,
+    providers,
+    config,
+    continuationStore,
+    providerStreamNormalizer,
   };
-}
 
-function shouldFailoverToNextProvider(error) {
-  if (isRecoverableError(error)) {
-    return true;
+  if (mode === 'roundtable') {
+    return await runRoundtablePipeline(common);
   }
-
-  const message = (error && error.message) || '';
-  return /(api key|authentication|unauthorized|forbidden|invalid|not available)/i.test(
-    message,
-  );
+  return await runParallelPipeline(common);
 }
 
-export function mapModelToProvider(model, providers) {
-  const modelLower = model.toLowerCase();
-
-  // Handle "auto" - prioritize: codex > gemini-cli > claude > copilot > openai
-  if (modelLower === 'auto') {
-    if (providers['codex']) {
-      return 'codex';
-    }
-    if (providers['gemini-cli']) {
-      return 'gemini-cli';
+/**
+ * Build the per-provider message array for a chat/consensus candidate. API and
+ * gemini-cli providers get the full role-separated history; last-user-only SDK
+ * providers get the prior transcript packed into a single final user message,
+ * except Codex in chat mode when it can resume its own thread.
+ */
+function makeMessageBuilder(common, priorTranscriptText, userMessage, packedUserMessage) {
+  const fullMessages = [common.systemMessage, ...common.normalizedHistory, userMessage];
+  return (candidate, callPlan) => {
+    if (!LAST_USER_ONLY.has(candidate.name)) {
+      return fullMessages;
     }
-    if (providers['claude']) {
-      return 'claude';
+    if (!priorTranscriptText) {
+      return [common.systemMessage, userMessage];
     }
-    if (providers['copilot']) {
-      return 'copilot';
+    const codexReusesThread =
+      common.mode === 'chat' &&
+      candidate.name === 'codex' &&
+      !!common.existingState?.providerThreads?.[callPlan.threadKey];
+    if (codexReusesThread) {
+      return fullMessages;
     }
-    return 'openai';
-  }
-
-  // Check Codex (exact match only - don't route "gpt-5-codex" etc to Codex provider)
-  if (modelLower === 'codex') {
-    return 'codex';
-  }
+    return [common.systemMessage, packedUserMessage];
+  };
+}
 
-  // Check Gemini CLI (exact match only - routes to CLI provider instead of Google API)
-  if (modelLower === 'gemini' || modelLower === 'gemini-cli') {
-    return 'gemini-cli';
-  }
+/**
+ * Parallel-mode pipeline (chat + consensus).
+ */
+async function runParallelPipeline(common) {
+  const {
+    mode,
+    models,
+    prompt,
+    reasoning_effort,
+    continuationId,
+    isCustomId,
+    existingState,
+    normalizedHistory,
+    contextMessage,
+    signal,
+    context,
+    providers,
+    config,
+    continuationStore,
+    providerStreamNormalizer,
+  } = common;
+
+  const userContent = contextMessage?.content
+    ? [...contextMessage.content, { type: 'text', text: prompt }]
+    : prompt;
+  const userMessage = { role: 'user', content: userContent };
+
+  const priorTranscriptText = renderStoredTranscriptToText(normalizedHistory);
+  const packedText = priorTranscriptText ? `${priorTranscriptText}\n\n${prompt}` : prompt;
+  const packedUserContent = contextMessage?.content
+    ? [...contextMessage.content, { type: 'text', text: packedText }]
+    : packedText;
+  const packedUserMessage = { role: 'user', content: packedUserContent };
+
+  const buildMessagesForCandidate = makeMessageBuilder(
+    common,
+    priorTranscriptText,
+    userMessage,
+    packedUserMessage,
+  );
 
-  // Check gemini: prefix (e.g., gemini:flash, gemini:pro) - routes to Antigravity
-  // CLI provider. Must be before the google flash/pro keyword rule so it wins.
-  if (modelLower.startsWith('gemini:')) {
-    return 'gemini-cli';
-  }
+  const optionsForCandidate = (candidate, callPlan) => {
+    const options = {
+      model: candidate.resolvedModel,
+      reasoning_effort,
+      config,
+    };
+    // Web search opt-in from an OpenRouter `:online` decoration (parsed by the
+    // shared resolver). Only ever set for OpenRouter candidates.
+    if (candidate.resolveOptions?.web_search) {
+      options.web_search = true;
+    }
+    // Codex thread reuse is chat-mode-scoped, and only Codex consumes these
+    // options — passing them to other providers would leak `threadKey` into
+    // their API payloads via generic option passthrough.
+    if (mode === 'chat' && candidate.name === 'codex') {
+      options.continuation_id = continuationId;
+      options.continuationStore = continuationStore;
+      options.threadKey = callPlan.threadKey;
+    }
+    return options;
+  };
 
-  // Check Claude SDK (exact match only - routes to SDK provider instead of Anthropic API)
-  if (
-    modelLower === 'claude' ||
-    modelLower === 'claude-sdk' ||
-    modelLower === 'claude-code'
-  ) {
-    return 'claude';
-  }
+  const startedAt = Date.now();
 
-  // Check claude: prefix (e.g., claude:fable, claude:opus) - routes to SDK provider
-  // Must be before keyword matching to prevent misrouting to Anthropic API
-  if (modelLower.startsWith('claude:')) {
-    return 'claude';
-  }
+  if (mode === 'consensus') {
+    const { resolved, preFailed } = resolveConsensusCallPlans(
+      models,
+      providers,
+      config,
+      common.images,
+    );
 
-  // Check Copilot SDK (exact match only - routes to SDK provider)
-  if (
-    modelLower === 'copilot' ||
-    modelLower === 'copilot-sdk' ||
-    modelLower === 'github-copilot'
-  ) {
-    return 'copilot';
-  }
+    if (resolved.length === 0) {
+      return {
+        error: createToolError(
+          'No providers available. Please configure at least one API key.',
+        ),
+        errorMessage: 'No providers available',
+      };
+    }
 
-  // Check copilot: prefix (e.g., copilot:gpt-5.2, copilot:claude-sonnet-4.6)
-  // Must be before slash-format and keyword matching to prevent misrouting
-  if (modelLower.startsWith('copilot:')) {
-    return 'copilot';
-  }
+    const { initial, refined } = await runConsensusMode({
+      callPlans: resolved,
+      buildMessagesForCandidate,
+      optionsForCandidate,
+      prompt,
+      signal,
+      context,
+      providerStreamNormalizer,
+    });
 
-  // Check OpenRouter-specific patterns first
-  if (
-    modelLower === 'openrouter auto' ||
-    modelLower === 'auto router' ||
-    modelLower === 'auto-router' ||
-    modelLower === 'openrouter-auto'
-  ) {
-    return 'openrouter';
-  }
+    const successful = initial.filter((r) => r.status === 'success');
+    const failed = [
+      ...initial.filter((r) => r.status === 'failed'),
+      ...preFailed.map((f) => ({ ...f, status: 'failed' })),
+    ];
 
-  // If model contains "/", check if native provider supports it
-  if (modelLower.includes('/')) {
-    // Check each provider to see if they have this exact model
-    for (const [providerName, provider] of Object.entries(providers)) {
-      if (provider && provider.getModelConfig) {
-        const modelConfig = provider.getModelConfig(model);
-        if (
-          modelConfig &&
-          !modelConfig.isDynamic &&
-          !modelConfig.needsApiUpdate
-        ) {
-          // Model exists in this provider's static list
-          return providerName;
-        }
-      }
-    }
-    // No native provider has this model, route to OpenRouter
-    return 'openrouter';
-  }
+    const formattedContent = formatConsensusContent(successful, refined);
 
-  // For non-slash models, use keyword matching as before
+    await persistAndExport(common, {
+      userMessage,
+      assistantContent: formattedContent,
+      extraState: {
+        consensusData: {
+          modelsRequested: models.length,
+          providersSuccessful: successful.length,
+          providersFailed: failed.length,
+        },
+      },
+    });
 
-  // OpenAI models
-  if (
-    modelLower.includes('gpt') ||
-    modelLower.includes('o1') ||
-    modelLower.includes('o3') ||
-    modelLower.includes('o4')
-  ) {
-    return 'openai';
+    const finalCount = refined
+      ? refined.filter((r) => r.status === 'success').length
+      : successful.length;
+    const totalCount = resolved.length;
+    const failureDetails = collectConsensusFailures(successful, failed, refined);
+    const combinedForSummary = successful
+      .map((r) => `${r.model}:\n${refined ? refinedText(refined, r) : r.response}`)
+      .join('\n\n---\n\n');
+
+    return {
+      kind: 'consensus',
+      continuationId,
+      isCustomId,
+      executionTime: (Date.now() - startedAt) / 1000,
+      structuredResult: {
+        status: 'consensus_complete',
+        models_consulted: models.length,
+        successful_initial_responses: successful.length,
+        failed_responses: failed.length,
+        refined_responses: refined
+          ? refined.filter((r) => r.status === 'success').length
+          : 0,
+        phases: {
+          initial: successful,
+          ...(refined !== null && { refined }),
+          failed,
+        },
+        continuation: {
+          id: continuationId,
+          messageCount: normalizedHistory.length + 3,
+          ...(isCustomId && { custom_id: true }),
+        },
+        settings: { models_requested: models },
+      },
+      formattedContent,
+      finalCount,
+      totalCount,
+      failureDetails,
+      modelsList: resolved.map((c) => c.displayModel).join(', '),
+      combinedForSummary,
+    };
   }
 
-  // XAI models
-  if (modelLower.includes('grok')) {
-    return 'xai';
+  // mode === 'chat'
+  const { callPlans, preFailed, error } = resolveChatCallPlans(
+    models,
+    providers,
+    config,
+    common.hasImages,
+  );
+  if (error) {
+    return { error: createToolError(error), errorMessage: error };
   }
 
-  // Google models
-  if (
-    modelLower.includes('flash') ||
-    modelLower.includes('pro') ||
-    modelLower === 'google'
-  ) {
-    return 'google';
+  const { results } = await runChatMode({
+    callPlans,
+    buildMessagesForCandidate,
+    optionsForCandidate,
+    signal,
+    context,
+    providerStreamNormalizer,
+    retryOptionsFor: (providerName) => getProviderRetryOptions(config, providerName),
+  });
+
+  const allResults = [
+    ...results,
+    ...preFailed.map((f) => ({ ...f, status: 'failed' })),
+  ];
+  const successful = allResults.filter((r) => r.status === 'success');
+
+  if (successful.length === 0) {
+    if (allResults.length > 1) {
+      // Multi-model all-failed: surface every model's failure.
+      const details = allResults.map((r) => `${r.model} (${r.error})`).join('; ');
+      return {
+        error: createToolError(`All models failed: ${details}`),
+        errorMessage: details,
+      };
+    }
+    const message =
+      allResults.find((r) => r.error)?.error || 'Provider returned no response';
+    return { error: createToolError(`Provider error: ${message}`), errorMessage: message };
   }
 
-  // Anthropic models
-  if (
-    modelLower.includes('claude') ||
-    modelLower.includes('fable') ||
-    modelLower.includes('opus') ||
-    modelLower.includes('sonnet') ||
-    modelLower.includes('haiku')
-  ) {
-    return 'anthropic';
-  }
+  const isMulti = models.length > 1;
+  const combinedContent = isMulti
+    ? formatChatMultiContent(successful)
+    : successful[0].response;
 
-  // Mistral models
-  if (modelLower.includes('mistral') || modelLower.includes('magistral')) {
-    return 'mistral';
+  // Merge new Codex thread IDs into the existing per-spec thread map.
+  const providerThreads = { ...(existingState?.providerThreads || {}) };
+  for (const r of successful) {
+    if (r.metadata?.threadId && r.threadKey) {
+      providerThreads[r.threadKey] = r.metadata.threadId;
+    }
   }
 
-  // DeepSeek models
-  if (
-    modelLower.includes('deepseek') ||
-    modelLower === 'reasoner' ||
-    modelLower === 'r1' ||
-    modelLower === 'chat'
-  ) {
-    return 'deepseek';
-  }
+  await persistAndExport(common, {
+    userMessage,
+    assistantContent: combinedContent,
+    extraState: { models, providerThreads },
+  });
 
-  // OpenRouter models (specific model patterns)
-  if (
-    modelLower.includes('qwen') ||
-    modelLower.includes('kimi') ||
-    modelLower.includes('moonshot') ||
-    modelLower === 'k2'
-  ) {
-    return 'openrouter';
-  }
+  const failed = allResults.filter((r) => r.status === 'failed');
+  const failureDetails = failed.map((f) => `${f.model} (${f.error})`);
+  const winner = successful[0];
+  const messageCount = normalizedHistory.length + 2; // user + assistant (system excluded)
 
-  // Default fallback
-  return 'openai';
+  return {
+    kind: 'chat',
+    continuationId,
+    isCustomId,
+    executionTime: (Date.now() - startedAt) / 1000,
+    content: combinedContent,
+    isMulti,
+    successCount: successful.length,
+    totalCount: allResults.length,
+    failureDetails,
+    messageCount,
+    modelsList: models.join(', '),
+    provider: winner.provider,
+    model: winner.resolvedModel,
+    combinedForSummary: combinedContent,
+  };
 }
 
 /**
- * Execute chat with streaming normalization for async execution
- * @param {object} args - Original chat arguments
- * @param {object} dependencies - Dependencies with continuationId
- * @param {object} context - Job execution context
- * @returns {Promise<object>} Complete chat result
+ * Roundtable-mode pipeline.
  */
-async function executeChatWithStreaming(args, dependencies, context) {
+async function runRoundtablePipeline(common) {
   const {
+    models,
+    prompt,
+    reasoning_effort,
+    continuationId,
+    isCustomId,
+    normalizedHistory,
+    systemPrompt,
+    contextMessage,
+    hasImages,
+    signal,
+    context,
+    providers,
     config,
+    providerStreamNormalizer,
+  } = common;
+
+  const startedAt = Date.now();
+
+  const lap = await runRoundtableLap({
+    models,
+    prompt,
+    priorHistory: normalizedHistory,
+    contextMessage,
+    systemPrompt,
     providers,
-    continuationStore,
-    contextProcessor,
+    config,
+    signal,
+    reasoning_effort,
+    hasImages,
+    context,
     providerStreamNormalizer,
+  });
+
+  const { lapTurns, transcript, turnsSuccessful, turnsFailed, lapUserMessage } = lap;
+
+  const conversationState = await persistAndExport(common, {
+    userMessage: lapUserMessage,
+    assistantContent: transcript,
+    extraState: {
+      roundtableData: {
+        modelsOrdered: models,
+        turnsSuccessful,
+        turnsFailed,
+      },
+    },
+  });
+
+  const failureDetails = lapTurns
+    .filter((t) => t.status === 'failed')
+    .map((t) => `${t.model} (${t.error})`);
+  const messageCount = (conversationState?.messages || []).length;
+  const combinedForSummary = lapTurns
+    .filter((t) => t.status === 'success' && t.response)
+    .map((t) => `${t.model}:\n${t.response}`)
+    .join('\n\n---\n\n');
+
+  return {
+    kind: 'roundtable',
     continuationId,
     isCustomId,
-    title: passedTitle, // Title passed from initial submission
-  } = dependencies;
+    executionTime: (Date.now() - startedAt) / 1000,
+    transcript,
+    structuredResult: {
+      status: 'roundtable_complete',
+      content: transcript,
+      models_consulted: models.length,
+      successful_turns: turnsSuccessful,
+      failed_turns: turnsFailed,
+      turns: lapTurns,
+      continuation: {
+        id: continuationId,
+        messageCount,
+        ...(isCustomId && { custom_id: true }),
+      },
+      settings: { models_requested: models },
+    },
+    turnsSuccessful,
+    totalTurns: lapTurns.length,
+    failureDetails,
+    modelsList: models.join(', '),
+    combinedForSummary,
+  };
+}
 
-  const {
-    prompt,
-    model = 'auto',
-    files = [],
-    temperature = 0.5,
-    use_websearch = false,
-    images = [],
-    reasoning_effort = 'medium',
-    verbosity = 'medium',
-    export: shouldExport = false,
-  } = args;
-
-  // Initialize SummarizationService
-  const summarizationService = new SummarizationService(providers, config);
+/**
+ * Build the synchronous MCP response from a pipeline result.
+ */
+function buildSyncResponse(pipeline, config) {
+  const isTest = config.environment?.nodeEnv === 'test';
+  const tokenLimit = getTokenLimit(config);
+  const idLine = `continuation_id: ${pipeline.continuationId}\n\n`;
+
+  if (pipeline.kind === 'chat') {
+    const statusLine = isTest
+      ? ''
+      : pipeline.isMulti
+        ? `✅ COMPLETED | CHAT | ${pipeline.continuationId} | ${pipeline.executionTime.toFixed(1)}s elapsed | ${pipeline.successCount}/${pipeline.totalCount} succeeded | ${pipeline.modelsList}\n`
+        : `✅ COMPLETED | CHAT | ${pipeline.continuationId} | ${pipeline.executionTime.toFixed(1)}s elapsed | ${pipeline.provider}/${pipeline.model}\n`;
 
-  // Use passed title or generate if not provided
-  let title = passedTitle;
-  if (!title) {
-    try {
-      title = await summarizationService.generateTitle(prompt);
-      debugLog(`Chat: Generated title - "${title}"`);
-    } catch (error) {
-      debugError('Chat: Failed to generate title', error);
-      // Continue without title if generation fails
+    const result = {
+      content: statusLine + idLine + pipeline.content,
+      continuation: {
+        id: pipeline.continuationId,
+        messageCount: pipeline.messageCount,
+        ...(pipeline.isMulti
+          ? { models: pipeline.modelsList }
+          : { provider: pipeline.provider, model: pipeline.model }),
+        ...(pipeline.isCustomId && { custom_id: true }),
+      },
+    };
+    if (pipeline.failureDetails.length > 0) {
+      result.content += formatFailureDetails(pipeline.failureDetails);
     }
-  } else {
-    debugLog(`Chat: Using passed title - "${title}"`);
-  }
 
-  let conversationHistory = [];
-
-  // Load existing conversation if continuation_id provided
-  if (continuationId) {
+    const limited = applyTokenLimit(JSON.stringify(result, null, 2), tokenLimit);
+    let finalResult;
     try {
-      const existingState = await continuationStore.get(continuationId);
-      if (existingState) {
-        conversationHistory = existingState.messages || [];
-      }
-    } catch (error) {
-      logger.error('Error loading conversation', { error });
-      // Continue with fresh conversation on error
+      finalResult = JSON.parse(limited.content);
+    } catch {
+      finalResult = result;
     }
+    return createToolResponse(finalResult);
   }
 
-  // Validate file paths before processing
-  if (files.length > 0 || images.length > 0) {
-    const validation = await validateAllPaths(
-      { files, images },
-      { clientCwd: config.server?.client_cwd },
-    );
-    if (!validation.valid) {
-      logger.error('File validation failed', { errors: validation.errors });
-      throw new Error(
-        `File validation failed: ${validation.errors.join(', ')}`,
-      );
-    }
+  // consensus / roundtable — structured JSON body
+  const modeLabel = pipeline.kind.toUpperCase();
+  const countField =
+    pipeline.kind === 'consensus'
+      ? `${pipeline.finalCount}/${pipeline.totalCount} succeeded`
+      : `${pipeline.turnsSuccessful}/${pipeline.totalTurns} turns`;
+  const statusLine = isTest
+    ? ''
+    : `✅ COMPLETED | ${modeLabel} | ${pipeline.continuationId} | ${pipeline.executionTime.toFixed(1)}s elapsed | ${countField} | ${pipeline.modelsList}\n`;
+
+  const limited = applyTokenLimit(
+    JSON.stringify(pipeline.structuredResult, null, 2),
+    tokenLimit,
+  );
+  let finalContent = limited.content;
+  if (pipeline.failureDetails.length > 0) {
+    finalContent += formatFailureDetails(pipeline.failureDetails);
   }
+  finalContent = statusLine + idLine + finalContent;
 
-  // Process context (files, images, web search)
-  let contextMessage = null;
-  if (files.length > 0 || images.length > 0 || use_websearch) {
-    try {
-      const contextRequest = {
-        files: Array.isArray(files) ? files : [],
-        images: Array.isArray(images) ? images : [],
-        webSearch: use_websearch ? prompt : null,
-      };
+  return createToolResponse({
+    content: finalContent,
+    continuation: pipeline.structuredResult.continuation,
+  });
+}
 
-      const contextResult = await contextProcessor.processUnifiedContext(
-        contextRequest,
-        {
-          enforceSecurityCheck: false,
-          skipSecurityCheck: true,
-          clientCwd: config.server?.client_cwd,
-        },
-      );
+/**
+ * Build the async job-completion result object from a pipeline result.
+ */
+function buildAsyncResult(pipeline, title, finalSummary) {
+  const baseMetadata = {
+    execution_time: pipeline.executionTime,
+    async_execution: true,
+    title,
+    final_summary: finalSummary,
+  };
 
-      // Create context message from files and images
-      const allProcessedFiles = [
-        ...contextResult.files,
-        ...contextResult.images,
-      ];
-      if (allProcessedFiles.length > 0) {
-        contextMessage = createFileContext(allProcessedFiles, {
-          includeMetadata: true,
-          includeErrors: true,
-        });
-      }
-    } catch (error) {
-      logger.error('Error processing context', { error });
-      // Continue without context if processing fails
-    }
+  if (pipeline.kind === 'chat') {
+    return {
+      status: 'chat_complete',
+      content: pipeline.content,
+      continuation: {
+        id: pipeline.continuationId,
+        messageCount: pipeline.messageCount,
+        ...(pipeline.isCustomId && { custom_id: true }),
+      },
+      metadata: {
+        ...baseMetadata,
+        provider: pipeline.provider,
+        model: pipeline.model,
+        successful_models: pipeline.successCount,
+        total_models: pipeline.totalCount,
+        failure_details: pipeline.failureDetails,
+      },
+    };
   }
 
-  // Build message array for provider
-  const messages = [];
-
-  // Add system prompt only if not already in conversation history
-  if (
-    conversationHistory.length === 0 ||
-    conversationHistory[0].role !== 'system'
-  ) {
-    messages.push({
-      role: 'system',
-      content: CHAT_PROMPT,
-    });
+  if (pipeline.kind === 'consensus') {
+    return {
+      ...pipeline.structuredResult,
+      content: pipeline.formattedContent,
+      continuation: {
+        id: pipeline.continuationId,
+        ...(pipeline.isCustomId && { custom_id: true }),
+      },
+      metadata: {
+        ...baseMetadata,
+        successful_models: pipeline.finalCount,
+        total_models: pipeline.totalCount,
+        failure_details: pipeline.failureDetails,
+      },
+    };
   }
 
-  // Add conversation history
-  messages.push(...conversationHistory);
-
-  // Add user prompt with context
-  const userMessage = {
-    role: 'user',
-    content: prompt,
+  // roundtable
+  return {
+    ...pipeline.structuredResult,
+    content: pipeline.transcript,
+    continuation: {
+      id: pipeline.continuationId,
+      ...(pipeline.isCustomId && { custom_id: true }),
+    },
+    metadata: {
+      ...baseMetadata,
+      successful_models: pipeline.turnsSuccessful,
+      total_models: pipeline.totalTurns,
+      failure_details: pipeline.failureDetails,
+    },
   };
+}
 
-  // If we have context (files/images), create complex content array
-  if (contextMessage && contextMessage.content) {
-    userMessage.content = [
-      ...contextMessage.content,
-      { type: 'text', text: prompt },
-    ];
-  }
-
-  messages.push(userMessage);
-
-  // Select provider
-  let selectedProvider;
-  let providerName;
-
-  if (model === 'auto') {
-    // Auto-select first available provider using same priority as sync path
-    const providerOrder = [
-      'codex',
-      'gemini-cli',
-      'claude',
-      'copilot',
-      'openai',
-      'google',
-      'xai',
-      'anthropic',
-      'mistral',
-      'deepseek',
-      'openrouter',
-    ];
+// --- Model resolution helpers ------------------------------------------------
 
-    const requestHasImages = Array.isArray(images) && images.length > 0;
+/**
+ * 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.
+ */
+function buildAutoCandidates(providers, config, hasImages) {
+  return getAvailableProviders(providers, config, { hasImages }).map((name) => ({
+    name,
+    providerInstance: providers[name],
+    resolvedModel: getDefaultModelForProvider(name),
+    displayModel: 'auto',
+  }));
+}
 
-    for (const name of providerOrder) {
-      const provider = providers[name];
-      if (provider && provider.isAvailable && provider.isAvailable(config)) {
-        // Skip text-only providers when the request includes images.
-        if (requestHasImages && !providerSupportsImages(provider, name)) {
-          continue;
+/**
+ * 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).
+ */
+function resolveChatCallPlans(models, providers, config, hasImages) {
+  const callPlans = [];
+  const preFailed = [];
+
+  for (const spec of models) {
+    if (String(spec).toLowerCase() === 'auto') {
+      const candidates = buildAutoCandidates(providers, config, hasImages);
+      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.
+        if (models.length === 1) {
+          return {
+            callPlans: [],
+            preFailed: [],
+            error:
+              'No providers available. Please configure at least one API key.',
+          };
         }
-        providerName = name;
-        selectedProvider = provider;
-        break;
+        preFailed.push({
+          model: 'auto',
+          error: 'No providers available for "auto".',
+        });
+        continue;
       }
+      callPlans.push({
+        modelSpec: spec,
+        displayModel: 'auto',
+        threadKey: spec,
+        candidates,
+      });
+      continue;
     }
 
-    if (!selectedProvider) {
-      throw new Error(
-        'No providers available. Please configure at least one API key.',
-      );
-    }
-  } else {
-    // Use specified provider/model
-    providerName = mapModelToProvider(model, providers);
-    selectedProvider = providers[providerName];
-
-    if (!selectedProvider) {
-      throw new Error(`Provider not found for model: ${model}`);
-    }
-
-    if (!selectedProvider.isAvailable(config)) {
-      throw new Error(getProviderUnavailableMessage(providerName));
+    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),
+      });
+    } else {
+      callPlans.push({
+        modelSpec: spec,
+        displayModel: spec,
+        threadKey: spec,
+        candidates: [
+          { name: providerName, providerInstance: provider, resolvedModel, displayModel: spec, resolveOptions: options },
+        ],
+      });
     }
   }
+  return { callPlans, preFailed, error: null };
+}
 
-  // Resolve model name and prepare provider options
-  const resolvedModel = resolveAutoModel(model, providerName);
-  const providerOptions = {
-    model: resolvedModel,
-    temperature,
-    reasoning_effort,
-    verbosity,
-    use_websearch,
-    config,
-    continuation_id: continuationId, // Pass for thread resumption
-    continuationStore, // Pass store for state management
-  };
-
-  // For streaming, add the stream flag and signal separately
-  const streamingOptions = {
-    ...providerOptions,
-    stream: true,
-    signal: context?.signal, // Pass AbortSignal for cancellation support
-  };
-
-  // Check if provider supports streaming (by checking if invoke can return a stream)
-  let response;
-  const startTime = Date.now();
-
-  // Always use streaming for async execution in background
-  if (context?.jobId) {
-    // Use streaming with normalization
-    debugLog(`Chat: Using streaming for provider ${providerName}`);
-
-    const stream = await selectedProvider.invoke(messages, streamingOptions);
-    const normalizedStream = providerStreamNormalizer.normalize(
-      providerName,
-      stream,
-      {
-        provider: providerName,
-        model: resolvedModel,
-        requestId: context.jobId,
-      },
-    );
-
-    // Process normalized stream and build final response
-    let accumulatedContent = '';
-    let finalUsage = null;
-    let finalMetadata = {};
-
-    for await (const event of normalizedStream) {
-      // Check for cancellation
-      if (context.signal.aborted) {
-        throw new Error('Chat execution was cancelled');
-      }
+/**
+ * Resolve consensus-mode call plans. Single "auto" expands to the first 3
+ * available providers' default models; each spec becomes a single-candidate plan.
+ */
+function resolveConsensusCallPlans(models, providers, config, images) {
+  const hasImages = Array.isArray(images) && images.length > 0;
 
-      switch (event.type) {
-      case 'start':
-        // Update job with streaming started status, provider info, and title
-        await context.updateJob({
-          status: 'running',
-          provider: providerName,
-          model: resolvedModel,
-          title: title || undefined, // Include title if generated
-          progress: {
-            phase: 'streaming_started',
-            provider: providerName,
-            model: resolvedModel,
-          },
-        });
-        break;
-
-      case 'delta':
-        accumulatedContent += event.data.textDelta;
-        // Update job with progress and full accumulated content
-        await context.updateJob({
-          accumulated_content: accumulatedContent, // Store full content
-          progress: {
-            phase: 'streaming',
-            provider: providerName,
-            model: resolvedModel,
-            content_length: accumulatedContent.length,
-          },
-        });
-        break;
+  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));
+  }
 
-      case 'reasoning_summary':
-        // Update job with reasoning summary
-        debugLog(
-          `[Chat] *** UPDATING JOB WITH REASONING: "${event.data.content?.substring(0, 100)}..."`,
-        );
-        await context.updateJob({
-          reasoning_summary: event.data.content,
-        });
-        break;
+  const resolved = [];
+  const preFailed = [];
+  for (const spec of modelsToProcess) {
+    if (!spec || typeof spec !== 'string') {
+      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) });
+    } else {
+      resolved.push({
+        modelSpec: spec,
+        displayModel: spec,
+        threadKey: spec,
+        candidates: [
+          { name: providerName, providerInstance: provider, resolvedModel, displayModel: spec, resolveOptions: options },
+        ],
+      });
+    }
+  }
+  return { resolved, preFailed };
+}
 
-      case 'usage':
-        finalUsage = event.data.usage;
-        break;
+// --- Formatting helpers ------------------------------------------------------
 
-      case 'end':
-        accumulatedContent = event.data.content || accumulatedContent;
-        finalUsage = event.data.usage || finalUsage;
-        finalMetadata = event.data.metadata || finalMetadata;
-        break;
+function formatChatMultiContent(successful) {
+  let content = '';
+  for (const r of successful) {
+    content += `### ${r.model}:\n${r.response}\n\n---\n\n`;
+  }
+  return content.trimEnd();
+}
 
-      case 'error':
-        throw new Error(`Streaming error: ${event.data.error.message}`);
+function formatConsensusContent(successful, refined) {
+  let content = '## Initial Responses\n\n';
+  for (const r of successful) {
+    content += `### ${r.model} (initial response):\n${r.response}\n\n---\n\n`;
+  }
+  if (refined) {
+    content += '## Refined Responses\n\n';
+    for (const r of refined) {
+      if (r.status === 'success' && r.refined_response) {
+        content += `### ${r.model} (refined response):\n${r.refined_response}\n\n---\n\n`;
+      } else if (r.status === 'partial') {
+        content += `### ${r.model} (refinement failed, showing initial):\n${r.initial_response}\n\n---\n\n`;
       }
     }
-
-    response = {
-      content: accumulatedContent,
-      metadata: {
-        ...finalMetadata,
-        usage: finalUsage,
-        streaming: true,
-      },
-    };
-  } else {
-    // Fall back to regular invoke
-    debugLog(`Chat: Using regular invoke for provider ${providerName}`);
-    response = await selectedProvider.invoke(messages, providerOptions);
   }
-
-  const executionTime = (Date.now() - startTime) / 1000;
-
-  // Validate response
-  if (!response || !response.content) {
-    throw new Error('Provider returned invalid response');
+  content += `\n**Summary:** Consensus completed with ${successful.length} successful initial responses`;
+  if (refined) {
+    const successfulRefinements = refined.filter((r) => r.status === 'success').length;
+    content += ` and ${successfulRefinements} successful refined responses`;
   }
+  content += '.';
+  return content;
+}
 
-  // Store reasoning summary from OpenAI if available
-  if (
-    response.metadata?.usage?.reasoning_summary &&
-    context &&
-    context.updateJob
-  ) {
-    try {
-      await context.updateJob({
-        reasoning_summary: response.metadata.usage.reasoning_summary,
-      });
-      debugLog('Chat: Stored reasoning summary');
-    } catch (error) {
-      debugError('Chat: Failed to store reasoning summary', error);
-    }
+function refinedText(refined, result) {
+  const match = refined.find((r) => r.model === result.model);
+  if (match && match.status === 'success' && match.refined_response) {
+    return match.refined_response;
   }
+  return result.response;
+}
 
-  // Generate final summary for responses longer than 100 characters (non-blocking)
-  let finalSummary = null;
-  if (response.content && response.content.length > 100) {
-    try {
-      finalSummary = await summarizationService.generateFinalSummary(
-        response.content,
-      );
-      debugLog(`Chat: Generated final summary - "${finalSummary}"`);
-      // Store final summary in job
-      if (finalSummary && context && context.updateJob) {
-        await context.updateJob({
-          final_summary: finalSummary,
-        });
+function collectConsensusFailures(successful, failed, refined) {
+  const details = [];
+  if (refined) {
+    refined.forEach((r) => {
+      if (r.status === 'partial') {
+        details.push(`${r.model} (refinement failed)`);
       }
-    } catch (error) {
-      debugError('Chat: Failed to generate final summary', error);
-      // Continue without summary if generation fails
-    }
+    });
+    failed.forEach((f) => details.push(`${f.model} (initial failed)`));
+  } else {
+    failed.forEach((f) => details.push(`${f.model} (${f.error})`));
   }
+  return details;
+}
 
-  // Add assistant response to conversation history
-  const assistantMessage = {
-    role: 'assistant',
-    content: response.content,
-  };
+// --- Shared side-effect + context helpers ------------------------------------
 
-  const updatedMessages = [...messages, assistantMessage];
+/**
+ * Build the persisted conversation state (aborted-guarded), persist it, export
+ * it when requested, and return it. Returns undefined when the request was
+ * aborted (matching the historical `const persist = !signal?.aborted` guard).
+ * @param {object} common - Shared pipeline context
+ * @param {object} parts - Varying per-mode parts
+ * @param {object} parts.userMessage - The turn's user message
+ * @param {string} parts.assistantContent - The assistant body to persist
+ * @param {object} [parts.extraState] - Extra per-mode state fields to merge
+ * @returns {Promise<object|undefined>} The persisted state, or undefined if skipped
+ */
+async function persistAndExport(common, { userMessage, assistantContent, extraState = {} }) {
+  if (common.signal?.aborted) {
+    return undefined;
+  }
+  const conversationState = {
+    messages: [
+      common.systemMessage,
+      ...common.normalizedHistory,
+      userMessage,
+      { role: 'assistant', content: assistantContent },
+    ],
+    mode: common.mode,
+    lastUpdated: Date.now(),
+    ...extraState,
+  };
+  await persistState(common.continuationStore, common.continuationId, conversationState);
+  await maybeExport(common.shouldExport, conversationState, {
+    config: common.config,
+    continuationId: common.continuationId,
+    models: common.models,
+    reasoning_effort: common.reasoning_effort,
+    mode: common.mode,
+    common,
+  });
+  return conversationState;
+}
 
-  // Save conversation state
+async function persistState(continuationStore, continuationId, state) {
   try {
-    const conversationState = {
-      messages: updatedMessages,
-      provider: providerName,
-      model,
-      lastUpdated: Date.now(),
-      // Store Codex thread ID if available (for thread resumption)
-      codexThreadId: response.metadata?.threadId,
-    };
-
-    await continuationStore.set(continuationId, conversationState);
+    await continuationStore.set(continuationId, state);
   } catch (error) {
     logger.error('Error saving conversation', { error });
-    // Continue even if save fails
   }
+}
+
+async function maybeExport(shouldExport, conversationState, opts) {
+  if (!shouldExport || !conversationState) {
+    return;
+  }
+  const { config, continuationId, models, reasoning_effort, mode, common } = opts;
+  await exportConversation(conversationState, {
+    clientCwd: config.server?.client_cwd,
+    continuation_id: continuationId,
+    mode,
+    models,
+    reasoning_effort,
+    files: common.files,
+    images: common.images,
+  });
+}
 
-  // Export conversation if requested
-  if (shouldExport) {
-    await exportConversation(
+/**
+ * Process files/images into a single context message (shared sync + async).
+ * @returns {Promise<object|null>} Context message or null
+ */
+async function buildContextMessage(files, images, contextProcessor, config) {
+  if ((!files || files.length === 0) && (!images || images.length === 0)) {
+    return null;
+  }
+  try {
+    const contextResult = await contextProcessor.processUnifiedContext(
       {
-        messages: updatedMessages,
-        provider: providerName,
-        model,
-        lastUpdated: Date.now(),
-        codexThreadId: response.metadata?.threadId,
+        files: Array.isArray(files) ? files : [],
+        images: Array.isArray(images) ? images : [],
       },
       {
+        enforceSecurityCheck: false,
+        skipSecurityCheck: true,
         clientCwd: config.server?.client_cwd,
-        continuation_id: continuationId,
-        model,
-        temperature,
-        reasoning_effort,
-        verbosity,
-        use_websearch,
-        files,
-        images,
       },
     );
+    const allProcessedFiles = [...contextResult.files, ...contextResult.images];
+    if (allProcessedFiles.length > 0) {
+      return createFileContext(allProcessedFiles, {
+        includeMetadata: true,
+        includeErrors: true,
+      });
+    }
+  } catch (error) {
+    logger.error('Error processing context', { error });
   }
+  return null;
+}
 
-  // Return complete result for job completion
-  return {
-    content: response.content,
-    title: title || undefined, // Include title if generated
-    summary: finalSummary || undefined, // Include summary if generated
-    continuation: {
-      id: continuationId,
-      provider: providerName,
-      model,
-      messageCount: updatedMessages.filter((msg) => msg.role !== 'system')
-        .length,
-      ...(isCustomId && { custom_id: true }),
-    },
-    metadata: {
-      provider: providerName,
-      model: resolvedModel,
-      execution_time: executionTime,
-      async_execution: true,
-      ...response.metadata,
-    },
-  };
+function formatStartTime() {
+  return new Date()
+    .toLocaleString('en-GB', {
+      day: '2-digit',
+      month: '2-digit',
+      year: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: false,
+    })
+    .replace(',', '');
 }
 
-// Tool metadata
+// --- Tool metadata -----------------------------------------------------------
+
 chatTool.description =
-  'GENERAL CHAT & COLLABORATIVE THINKING - Development assistance, brainstorming, code analysis. Supports files, images, continuation_id for multi-turn conversations. Use model: "auto" for automatic selection. IMPORTANT: Use the "files" parameter to share code/file content instead of pasting into the prompt.';
+  'UNIFIED CHAT — talk to one or more AI models. mode "chat" (default): 1..N models answer independently in parallel. mode "consensus": ≥2 models answer, then refine after seeing each other. mode "roundtable": models answer sequentially, each building on the running transcript. Supports files, images, and continuation_id for multi-turn threads (you may switch modes on resume). Use model "auto" for automatic selection. IMPORTANT: use the "files" parameter to share code/file content instead of pasting into the prompt.';
+
 chatTool.inputSchema = {
   type: 'object',
   properties: {
-    model: {
+    prompt: {
       type: 'string',
       description:
-        'AI model to use. Examples: "auto" (recommended), "codex", "gemini", "gemini:flash", "claude", "claude:fable", "claude:opus", "copilot", "copilot:codex". Defaults to auto-selection.',
+        'Your question, topic, or task with relevant context. More detail enables better responses. Example: "How should I structure the authentication module for this Express.js API?"',
     },
-    files: {
+    models: {
       type: 'array',
       items: { type: 'string' },
+      minItems: 1,
       description:
-        'File paths to include as context (absolute or relative paths). Supports line ranges: file.txt{10:50}, file.txt{100:}. Example: ["./src/utils/auth.js{50:100}", "./config.json"]. IMPORTANT: Always use this parameter to share file content instead of copying code into the prompt - it provides better formatting, line numbers, and preserves context.',
+        '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"].',
     },
-    images: {
-      type: 'array',
-      items: { type: 'string' },
+    mode: {
+      type: 'string',
+      enum: ['chat', 'consensus', 'roundtable'],
       description:
-        'Image paths for visual context (absolute or relative paths, or base64 data). Example: ["C:\\Users\\username\\diagram.png", "./screenshot.jpg", "data:image/jpeg;base64,/9j/4AAQ..."]',
+        'Execution mode. "chat" (default): independent parallel answers. "consensus": ≥2 models answer then refine via cross-feedback. "roundtable": sequential turn-based dialogue in the given model order. Default: "chat".',
     },
     continuation_id: {
       type: 'string',
       description:
-        'Continuation ID for persistent conversation. Auto-generated in the first response; pass it back to continue the conversation.',
+        'Continuation ID for a persistent multi-turn thread. Auto-generated in the first response; pass it back to continue. You MAY change the mode or models on a resuming turn.',
     },
-    temperature: {
-      type: 'number',
+    files: {
+      type: 'array',
+      items: { type: 'string' },
       description:
-        'Response randomness (0.0-1.0). Examples: 0.2 (focused), 0.5 (balanced), 0.8 (creative). Default: 0.5',
-      minimum: 0.0,
-      maximum: 1.0,
-      default: 0.5,
+        'File paths to include as context (absolute or relative). Supports line ranges: file.txt{10:50}, file.txt{100:}. Example: ["./src/utils/auth.js{50:100}", "./config.json"]. IMPORTANT: Always use this parameter to share file content instead of copying code into the prompt.',
     },
-    reasoning_effort: {
-      type: 'string',
-      enum: ['none', 'minimal', 'low', 'medium', 'high', 'max'],
+    images: {
+      type: 'array',
+      items: { type: 'string' },
       description:
-        'Reasoning depth for thinking models. Examples: "none" (no reasoning, fastest - GPT-5.1+ only), "minimal" (few reasoning tokens), "low" (light analysis), "medium" (balanced), "high" (complex analysis). Default: "medium"',
-      default: 'medium',
+        'Image paths for visual context (absolute or relative paths, or base64 data). Example: ["C:\\Users\\username\\diagram.png", "./screenshot.jpg", "data:image/jpeg;base64,/9j/4AAQ..."]',
     },
-    verbosity: {
+    reasoning_effort: {
       type: 'string',
-      enum: ['low', 'medium', 'high'],
-      description:
-        'Output verbosity for GPT-5 models. Examples: "low" (concise answers), "medium" (balanced), "high" (thorough explanations). Default: "medium"',
-      default: 'medium',
-    },
-    use_websearch: {
-      type: 'boolean',
+      enum: ['none', 'minimal', 'low', 'medium', 'high', 'max'],
       description:
-        'Enable web search for current information. Example: true for recent developments or up to date documentation. Default: false',
-      default: false,
+        'Reasoning depth for thinking models. Examples: "none" (no reasoning, fastest - GPT-5.1+ only), "minimal", "low", "medium" (balanced), "high", "max". Default: "medium"',
     },
     async: {
       type: 'boolean',
       description:
-        'Execute chat in background. When true, returns continuation_id immediately and processes request asynchronously. Default: false',
-      default: false,
+        'Execute in the background. When true, returns a continuation_id immediately and processes the request asynchronously; poll with check_status. Default: false',
     },
     export: {
       type: 'boolean',
       description:
-        'Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata. Default: false',
-      default: false,
-    },
-    prompt: {
-      type: 'string',
-      description:
-        'Your question or topic with relevant context. More detail enables better responses. Example: "How should I structure the authentication module for this Express.js API?"',
+        'Export the conversation to disk. Creates a folder named for the continuation_id with numbered request/response files and metadata. Default: false',
     },
   },
   required: ['prompt'],