converse-mcp-server 3.7.1 → 4.1.0

package/src/tools/chat.js

@@ -29,9 +29,8 @@ import { SummarizationService } from '../services/summarizationService.js';
 import { exportConversation } from '../utils/conversationExporter.js';
 import { EFFORT_LADDER } from '../utils/reasoningEffort.js';
 import {
-  getDefaultModelForProvider,
-  getProviderUnavailableMessage,
-  getAvailableProviders,
+  getAutoCandidates,
+  getAutoModelSpecs,
   resolveModelSpec,
 } from '../utils/modelRouting.js';
 import {
@@ -857,24 +856,52 @@ function buildAsyncResult(pipeline, title, finalSummary) {
 // --- Model resolution helpers ------------------------------------------------
 
 /**
- * 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.
+ * Convert router candidates into the engine's call-plan candidate shape.
  */
-function buildAutoCandidates(providers, config, hasImages) {
-  return getAvailableProviders(providers, config, { hasImages }).map((name) => ({
-    name,
-    providerInstance: providers[name],
-    resolvedModel: getDefaultModelForProvider(name),
-    displayModel: 'auto',
+function toPlanCandidates(candidates, displayModel) {
+  return candidates.map((c) => ({
+    name: c.providerName,
+    providerInstance: c.provider,
+    resolvedModel: c.resolvedModel,
+    displayModel,
+    resolveOptions: c.options,
   }));
 }
 
+/**
+ * Resolve one explicit spec into a call plan, or a pre-failed entry carrying
+ * the router's error (unknown names include "did you mean" suggestions). A
+ * bare model name served by several providers yields a multi-candidate plan
+ * that fails over in provider priority order.
+ */
+function resolveExplicitPlan(spec, providers, config) {
+  const resolution = resolveModelSpec(spec, providers, config);
+  if (resolution.status !== 'ok') {
+    return {
+      preFailed: {
+        model: spec,
+        ...(resolution.providerName && { provider: resolution.providerName }),
+        error: resolution.error,
+      },
+    };
+  }
+  return {
+    plan: {
+      modelSpec: spec,
+      displayModel: spec,
+      threadKey: spec,
+      candidates: toPlanCandidates(resolution.candidates, spec),
+    },
+  };
+}
+
 /**
  * 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).
+ * plan each, with failover candidates when a bare name is served by several
+ * providers. Unavailable/unknown explicit models are returned as pre-failed
+ * entries (surfaced as per-model failures).
  */
 function resolveChatCallPlans(models, providers, config, hasImages) {
   const callPlans = [];
@@ -882,7 +909,10 @@ function resolveChatCallPlans(models, providers, config, hasImages) {
 
   for (const spec of models) {
     if (String(spec).toLowerCase() === 'auto') {
-      const candidates = buildAutoCandidates(providers, config, hasImages);
+      const candidates = toPlanCandidates(
+        getAutoCandidates(providers, config, { hasImages }),
+        'auto',
+      );
       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.
@@ -909,28 +939,11 @@ function resolveChatCallPlans(models, providers, config, hasImages) {
       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 for model: ${spec}`,
-      });
-    } else if (status === 'unavailable') {
-      preFailed.push({
-        model: spec,
-        provider: providerName,
-        error: getProviderUnavailableMessage(providerName),
-      });
+    const { plan, preFailed: failed } = resolveExplicitPlan(spec, providers, config);
+    if (failed) {
+      preFailed.push(failed);
     } else {
-      callPlans.push({
-        modelSpec: spec,
-        displayModel: spec,
-        threadKey: spec,
-        candidates: [
-          { name: providerName, providerInstance: provider, resolvedModel, displayModel: spec, resolveOptions: options },
-        ],
-      });
+      callPlans.push(plan);
     }
   }
   return { callPlans, preFailed, error: null };
@@ -938,15 +951,15 @@ function resolveChatCallPlans(models, providers, config, hasImages) {
 
 /**
  * Resolve consensus-mode call plans. Single "auto" expands to the first 3
- * available providers' default models; each spec becomes a single-candidate plan.
+ * available providers' default models (as `namespace:model` specs); each spec
+ * becomes one plan.
  */
 function resolveConsensusCallPlans(models, providers, config, images) {
   const hasImages = Array.isArray(images) && images.length > 0;
 
   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));
+    modelsToProcess = getAutoModelSpecs(providers, config, { hasImages, limit: 3 });
   }
 
   const resolved = [];
@@ -956,20 +969,11 @@ function resolveConsensusCallPlans(models, providers, config, images) {
       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) });
+    const { plan, preFailed: failed } = resolveExplicitPlan(spec, providers, config);
+    if (failed) {
+      preFailed.push(failed);
     } else {
-      resolved.push({
-        modelSpec: spec,
-        displayModel: spec,
-        threadKey: spec,
-        candidates: [
-          { name: providerName, providerInstance: provider, resolvedModel, displayModel: spec, resolveOptions: options },
-        ],
-      });
+      resolved.push(plan);
     }
   }
   return { resolved, preFailed };
@@ -1161,7 +1165,7 @@ chatTool.inputSchema = {
       items: { type: 'string' },
       minItems: 1,
       description:
-        '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"].',
+        'Models to use. Examples: ["auto"] (recommended), ["codex"], ["codex", "gemini", "claude"], ["codex:astra"], ["gpt-6-astra"]. Forms: "provider" (its default model), "provider:model" (that provider only), or a bare "model" (served by the first configured provider that offers it, local CLI providers first, failing over to the next). Providers: codex, gemini (agy), claude, copilot, openai, google, xai, anthropic, mistral, deepseek, openrouter. Unknown names are rejected with suggestions. 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"].',
     },
     mode: {
       type: 'string',

package/src/tools/decide.js

@@ -0,0 +1,312 @@
+/**
+ * Decide Tool - System One decision models
+ *
+ * Asks a decision model (TypeSafe's Jev family) typed questions about a state
+ * and returns calibrated answers: a probability for yes/no questions, a
+ * probability distribution for choices and rubric scores. Decision models
+ * never generate text, so this is a separate tool rather than a chat mode.
+ */
+
+import { createToolResponse, createToolError } from './index.js';
+import { resolveDecisionModel } from '../decisionProviders/index.js';
+import { callSystemOne } from '../decisionProviders/systemOne.js';
+import { validateAllPaths } from '../utils/fileValidator.js';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('decide');
+
+const QUESTION_TYPES = ['noul', 'choice', 'score'];
+const QUESTION_FIELDS = ['type', 'instructions', 'criteria'];
+const MAX_CHOICE_OPTIONS = 255;
+const MIN_SCORE_LEVELS = 2;
+const MAX_SCORE_LEVELS = 10;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Criteria descriptions may be plain text or structured reference data. */
+function isCriterionValue(value) {
+  return (typeof value === 'string' && value.trim() !== '') || isPlainObject(value) || Array.isArray(value);
+}
+
+function validateState(state) {
+  if (typeof state === 'string') {
+    return state.trim() ? null : '"state" must not be empty.';
+  }
+  if (isPlainObject(state) || Array.isArray(state)) return null;
+  return '"state" must be a string, an object, or an array.';
+}
+
+function validateQuestion(key, question) {
+  const at = `questions.${key}`;
+  if (!isPlainObject(question)) return `${at} must be an object with "type" and "instructions".`;
+
+  const unknown = Object.keys(question).filter((f) => !QUESTION_FIELDS.includes(f));
+  if (unknown.length) {
+    return `${at} has unknown field(s): ${unknown.join(', ')}. Allowed: ${QUESTION_FIELDS.join(', ')}.`;
+  }
+  if (!QUESTION_TYPES.includes(question.type)) {
+    return `${at}.type must be one of: ${QUESTION_TYPES.join(', ')}.`;
+  }
+
+  const { instructions, criteria } = question;
+  const hasInstructions =
+    (typeof instructions === 'string' && instructions.trim() !== '') ||
+    (isPlainObject(instructions) && Object.keys(instructions).length > 0) ||
+    (Array.isArray(instructions) && instructions.length > 0);
+  if (!hasInstructions) {
+    return `${at}.instructions must be a non-empty string, object, or array.`;
+  }
+
+  if (question.type === 'noul') {
+    if (criteria === undefined) return null;
+    const keys = isPlainObject(criteria) ? Object.keys(criteria).sort() : null;
+    if (!keys || keys.join(',') !== 'false,true' || !isCriterionValue(criteria.true) || !isCriterionValue(criteria.false)) {
+      return `${at}.criteria for a noul question must be { "true": "...", "false": "..." } with both descriptions.`;
+    }
+    return null;
+  }
+
+  if (question.type === 'choice') {
+    if (!isPlainObject(criteria)) {
+      return `${at}.criteria for a choice question must map option names to descriptions (or null).`;
+    }
+    const options = Object.entries(criteria);
+    if (options.length < 2 || options.length > MAX_CHOICE_OPTIONS) {
+      return `${at}.criteria must have 2 to ${MAX_CHOICE_OPTIONS} options (got ${options.length}).`;
+    }
+    const bad = options.filter(([, v]) => v !== null && !isCriterionValue(v)).map(([k]) => k);
+    if (bad.length) {
+      return `${at}.criteria option(s) ${bad.join(', ')} need a description string, object, array, or null.`;
+    }
+    return null;
+  }
+
+  if (!Array.isArray(criteria)) {
+    return `${at}.criteria for a score question must be an ordered array of level descriptions.`;
+  }
+  if (criteria.length < MIN_SCORE_LEVELS || criteria.length > MAX_SCORE_LEVELS) {
+    return `${at}.criteria must have ${MIN_SCORE_LEVELS} to ${MAX_SCORE_LEVELS} levels (got ${criteria.length}).`;
+  }
+  if (!criteria.every(isCriterionValue)) {
+    return `${at}.criteria levels must each be a non-empty description.`;
+  }
+  return null;
+}
+
+/**
+ * Check questions locally: the API reports schema faults as nested validation
+ * dumps, and a local message is both clearer and free.
+ * @returns {string|null} First problem found
+ */
+export function validateQuestions(questions) {
+  if (!isPlainObject(questions) || Object.keys(questions).length === 0) {
+    return '"questions" must be an object with at least one named question.';
+  }
+  for (const [key, question] of Object.entries(questions)) {
+    if (!key.trim()) return 'Question names must not be empty.';
+    const error = validateQuestion(key, question);
+    if (error) return error;
+  }
+  return null;
+}
+
+/**
+ * Read files into a `{ path: content }` map. Every file must load as text:
+ * a silently missing file would change the state being judged.
+ */
+async function loadFiles(files, contextProcessor, config) {
+  const validation = await validateAllPaths(
+    { files },
+    { clientCwd: config?.server?.client_cwd },
+  );
+  if (!validation.valid) {
+    return { error: validation.errors.join('; ') };
+  }
+
+  const result = await contextProcessor.processUnifiedContext(
+    { files },
+    { enforceSecurityCheck: false, skipSecurityCheck: true, clientCwd: config?.server?.client_cwd },
+  );
+  const problems = [];
+  const contents = {};
+  for (const file of result.files) {
+    if (file.type === 'error') {
+      problems.push(`${file.originalPath}: ${file.error}`);
+    } else if (file.type !== 'text') {
+      problems.push(`${file.originalPath}: decision models accept text only`);
+    } else {
+      contents[file.originalPath] = file.content;
+    }
+  }
+  if (result.errors?.length) problems.push(...result.errors.map((e) => e.message));
+  return problems.length ? { error: problems.join('; ') } : { contents };
+}
+
+function fixed(n) {
+  return typeof n === 'number' ? n.toFixed(2) : String(n);
+}
+
+function byProbability(probabilities, label = (k) => k) {
+  return Object.entries(probabilities || {})
+    .sort(([, a], [, b]) => b - a)
+    .map(([k, p]) => `${label(k)} ${fixed(p)}`)
+    .join(', ');
+}
+
+function summarizeAnswer(key, answer) {
+  const type = answer?.type ?? 'unknown';
+  if (type === 'noul') {
+    return `- ${key} (noul): ${fixed(answer.noul)}`;
+  }
+  if (type === 'choice') {
+    return `- ${key} (choice): ${answer.choice} · confidence ${fixed(answer.confidence)} · ${byProbability(answer.probabilities)}`;
+  }
+  if (type === 'score') {
+    const levels = Object.keys(answer.legend || answer.probabilities || {});
+    const range = levels.length ? ` on 0–${levels.length - 1}` : '';
+    const label = (k) => (answer.legend?.[k] ? `${k} ${answer.legend[k]}` : k);
+    return `- ${key} (score): ${fixed(answer.score)}${range} · confidence ${fixed(answer.confidence)} · ${byProbability(answer.probabilities, label)}`;
+  }
+  return `- ${key} (${type}): ${JSON.stringify(answer)}`;
+}
+
+function formatResult(response, candidate, failures) {
+  const usage = response.usage || {};
+  const header = [
+    `Decision · ${response.model || candidate.model} via ${candidate.provider.label}`,
+    usage.input_tokens !== undefined ? `${usage.input_tokens} input tokens` : null,
+    typeof usage.cost === 'number' ? `$${usage.cost.toFixed(6)}` : null,
+  ].filter(Boolean).join(' · ');
+
+  const lines = [header];
+  for (const failure of failures) {
+    lines.push(`(${failure.provider} failed, fell back: ${failure.message})`);
+  }
+  lines.push(...Object.entries(response.answers).map(([key, answer]) => summarizeAnswer(key, answer)));
+
+  const payload = {
+    model: response.model ?? candidate.model,
+    provider: candidate.providerName,
+    answers: response.answers,
+    usage: {
+      input_tokens: usage.input_tokens ?? null,
+      output_tokens: usage.output_tokens ?? null,
+      cost: typeof usage.cost === 'number' ? usage.cost : null,
+    },
+    ...(response.id ? { id: response.id } : {}),
+  };
+  return `${lines.join('\n')}\n\n\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
+}
+
+/**
+ * Decide MCP Tool
+ * @param {object} args - Tool arguments
+ * @param {string|object|Array} [args.state] - Material to judge
+ * @param {object} args.questions - Named typed questions
+ * @param {string} [args.model] - Model spec, default "auto"
+ * @param {string[]} [args.files] - Text files added to the state
+ * @param {object} dependencies - Injected dependencies (config, contextProcessor, signal)
+ * @returns {Promise<object>} MCP tool response
+ */
+export async function decideTool(args, dependencies) {
+  const { config, contextProcessor, signal } = dependencies;
+  const { state, questions, model = 'auto', files = [] } = args;
+
+  if (!Array.isArray(files) || !files.every((f) => typeof f === 'string' && f.trim())) {
+    return createToolError('"files" must be an array of file paths.');
+  }
+  if (state === undefined && files.length === 0) {
+    return createToolError('Provide "state", "files", or both: there is nothing to judge.');
+  }
+  const stateError = state === undefined ? null : validateState(state);
+  if (stateError) return createToolError(stateError);
+  const questionError = validateQuestions(questions);
+  if (questionError) return createToolError(questionError);
+
+  const route = resolveDecisionModel(model, config);
+  if (route.status !== 'ok') return createToolError(route.error);
+
+  let finalState = state;
+  if (files.length > 0) {
+    const loaded = await loadFiles(files, contextProcessor, config);
+    if (loaded.error) return createToolError(`Could not load files: ${loaded.error}`);
+    finalState = state === undefined ? { files: loaded.contents } : { input: state, files: loaded.contents };
+  }
+
+  const failures = [];
+  for (const candidate of route.candidates) {
+    try {
+      const response = await callSystemOne({
+        baseURL: candidate.provider.baseURL,
+        headers: candidate.provider.headers(config),
+        body: { model: candidate.model, state: finalState, questions },
+        signal,
+      });
+      return createToolResponse(formatResult(response, candidate, failures));
+    } catch (error) {
+      if (signal?.aborted) return createToolError('Decision request cancelled.');
+      logger.error('Decision request failed', { provider: candidate.providerName, model: candidate.model, error: error.message });
+      failures.push({ provider: candidate.providerName, message: error.message });
+      if (error.terminal) break;
+    }
+  }
+
+  const detail = failures.map((f) => `${f.provider}: ${f.message}`).join('; ');
+  return createToolError(`Decision request failed (${detail})`);
+}
+
+decideTool.description =
+  'DECIDE — ask a System One decision model (TypeSafe Jev) typed questions about a state and get calibrated answers, not text. ' +
+  'Question types: "noul" (yes/no → probability 0..1), "choice" (pick one of 2–255 named options → choice, per-option probabilities, confidence), ' +
+  '"score" (ordered rubric of 2–10 levels → weighted position, per-level probabilities, confidence). ' +
+  'Batch many questions into one call: they are judged in parallel and in isolation against the same state at almost no extra cost. ' +
+  'Best for fast atomic judgments (classify, route, verify, rank). Keep each question literal and narrow; do counting, arithmetic, and date comparison in code; ' +
+  'split compound judgments into separate questions; treat low confidence as a signal to escalate. Text only, no explanations are returned. ' +
+  'Limits: ~64k tokens per request, ~32k for state plus the longest question.';
+
+decideTool.inputSchema = {
+  type: 'object',
+  properties: {
+    state: {
+      anyOf: [{ type: 'string' }, { type: 'object' }, { type: 'array' }],
+      description:
+        'The material to judge: plain text, or JSON (an object with descriptively named fields is best; an array for sequences such as messages). Optional when "files" is given.',
+    },
+    questions: {
+      type: 'object',
+      description:
+        'Named questions, all answered against the same state. The name is your own label and is returned as the answer key. ' +
+        'Each question: { "type": "noul"|"choice"|"score", "instructions": string|object|array, "criteria": ... }. ' +
+        'criteria — noul: optional { "true": "...", "false": "..." }; choice: required { "<option>": "description" | null } (2–255 options); ' +
+        'score: required ordered array of level descriptions, lowest first (2–10 levels). ' +
+        'instructions may be an object bundling the question with reference data, referenced by `name` in the text. ' +
+        'Example: { "team": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments, refunds", "technical": "Bugs, outages" } } }',
+      additionalProperties: {
+        type: 'object',
+        properties: {
+          type: { type: 'string', enum: QUESTION_TYPES },
+          instructions: { anyOf: [{ type: 'string' }, { type: 'object' }, { type: 'array' }] },
+          criteria: { anyOf: [{ type: 'object' }, { type: 'array' }] },
+        },
+        required: ['type', 'instructions'],
+        additionalProperties: false,
+      },
+    },
+    model: {
+      type: 'string',
+      description:
+        'Decision model. "auto" (default): TypeSafe, falling back to OpenRouter. "jev-latest", "jev-1.13": first configured provider that serves it, with fallback. ' +
+        '"typesafe:jev-1.13.0", "openrouter:~typesafe/jev-latest": that provider only. Providers: typesafe (TYPESAFE_API_KEY), openrouter (OPENROUTER_API_KEY).',
+    },
+    files: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Text files added to the state as { "files": { "<path>": "<content>" } }; a given state moves to "input". Supports line ranges: file.txt{10:50}. Images are rejected.',
+    },
+  },
+  required: ['questions'],
+  additionalProperties: false,
+};

package/src/tools/index.js

@@ -9,6 +9,7 @@
 import { chatTool } from './chat.js';
 import { checkStatusTool } from './checkStatus.js';
 import { cancelJobTool } from './cancelJob.js';
+import { decideTool } from './decide.js';
 
 /**
  * Tool registry map
@@ -19,6 +20,7 @@ const tools = {
   chat: chatTool,
   check_status: checkStatusTool,
   cancel_job: cancelJobTool,
+  decide: decideTool,
 };
 
 /**

package/src/tools/modes/roundtable.js

@@ -20,12 +20,8 @@
 
 import { debugLog } from '../../utils/console.js';
 import { acquireProviderStream } from './streamShared.js';
-import {
-  getDefaultModelForProvider,
-  getProviderUnavailableMessage,
-  getAvailableProviders,
-  resolveModelSpec,
-} from '../../utils/modelRouting.js';
+import { getAutoModelSpecs, resolveModelSpec } from '../../utils/modelRouting.js';
+import { shouldFailoverToNextProvider } from './parallel.js';
 
 /**
  * Render a stored transcript (from prior laps or a prior chat/consensus thread)
@@ -169,7 +165,9 @@ export function formatLapTranscript(lapTurns) {
  * 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).
+ * turn). A bare model name served by several providers carries every serving
+ * provider in `candidates`, tried in order when a turn fails with a
+ * failover-worthy error.
  * @param {Array<string>} models - Ordered model list
  * @param {object} providers - Provider instances
  * @param {object} config - Configuration
@@ -181,16 +179,14 @@ export function resolveTurnPlan(models, providers, config, hasImages = false) {
   // (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, {
+    const [firstAvailable] = getAutoModelSpecs(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'];
+    modelsToProcess = firstAvailable ? [firstAvailable] : ['auto'];
   }
 
   return modelsToProcess.map((modelName) => {
@@ -200,39 +196,31 @@ export function resolveTurnPlan(models, providers, config, hasImages = false) {
         provider: null,
         providerInstance: null,
         resolvedModel: null,
+        candidates: [],
         preFailReason: 'Invalid model specification',
       };
     }
 
-    const { providerName, provider, resolvedModel, status, options } =
-      resolveModelSpec(modelName, providers, config);
+    const resolution = resolveModelSpec(modelName, providers, config);
 
-    if (status === 'not_found') {
+    if (resolution.status !== 'ok') {
       return {
         model: modelName,
-        provider: providerName,
+        provider: resolution.providerName,
         providerInstance: null,
-        resolvedModel,
-        preFailReason: `Provider not found: ${providerName}`,
-      };
-    }
-
-    if (status === 'unavailable') {
-      return {
-        model: modelName,
-        provider: providerName,
-        providerInstance: null,
-        resolvedModel,
-        preFailReason: getProviderUnavailableMessage(providerName),
+        resolvedModel: null,
+        candidates: [],
+        preFailReason: resolution.error,
       };
     }
 
     return {
       model: modelName,
-      provider: providerName,
-      providerInstance: provider,
-      resolvedModel,
-      resolveOptions: options,
+      provider: resolution.providerName,
+      providerInstance: resolution.provider,
+      resolvedModel: resolution.resolvedModel,
+      resolveOptions: resolution.options,
+      candidates: resolution.candidates,
       preFailReason: null,
     };
   });
@@ -254,7 +242,9 @@ function buildTurnUserContent(packetText, contextMessage) {
  * 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 }
+ * @returns {Promise<object>} Turn result { model, provider, status, response|error };
+ *   failed turns also carry the thrown `cause` for the failover decision
+ *   (stripped before the turn is recorded)
  */
 async function executeTurn(
   plan,
@@ -353,6 +343,7 @@ async function executeTurn(
       provider: plan.provider,
       status: 'failed',
       error: error.message,
+      cause: error,
     };
   }
 }
@@ -436,24 +427,44 @@ export async function runRoundtableLap({
         { 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,
-      );
+      let turnResult;
+      for (let ci = 0; ci < plan.candidates.length; ci++) {
+        const candidate = plan.candidates[ci];
+        turnResult = await executeTurn(
+          {
+            model: plan.model,
+            provider: candidate.providerName,
+            providerInstance: candidate.provider,
+          },
+          messages,
+          {
+            reasoning_effort,
+            signal: activeSignal,
+            config,
+            model: candidate.resolvedModel,
+            // Web search opt-in from an OpenRouter `:online` decoration; only ever
+            // set for OpenRouter turns.
+            ...(candidate.options?.web_search && { web_search: true }),
+          },
+          context,
+          providerStreamNormalizer,
+          i,
+        );
+        const isLastCandidate = ci === plan.candidates.length - 1;
+        if (
+          turnResult.status === 'success' ||
+          isLastCandidate ||
+          !shouldFailoverToNextProvider(turnResult.cause)
+        ) {
+          break;
+        }
+        debugLog(
+          `[Roundtable] Turn ${i + 1} (${plan.model}) failed on ${candidate.providerName}; failing over`,
+        );
+      }
 
-      lapTurns.push({ ...turnResult, position: i });
+      const { cause: _cause, ...turn } = turnResult;
+      lapTurns.push({ ...turn, position: i });
     }
 
     if (context) {