dialectic 0.1.0

package/src/utils/progress-ui.ts

@@ -0,0 +1,313 @@
+import { ContributionType, CONTRIBUTION_TYPES } from '../types/debate.types';
+import { writeStderr } from '../cli/index';
+
+// Lazy load chalk for optional color support
+let chalk: any;
+try {
+  chalk = require('chalk');
+} catch {
+  // If chalk is not available, create a pass-through mock
+  chalk = new Proxy({}, {
+    get: () => (text: string) => text
+  });
+}
+
+// Constants for UI strings and configuration
+const PHASE_LABELS = {
+  [CONTRIBUTION_TYPES.PROPOSAL]: 'Proposals',
+  [CONTRIBUTION_TYPES.CRITIQUE]: 'Critiques',
+  [CONTRIBUTION_TYPES.REFINEMENT]: 'Refinements',
+} as const;
+
+const SYNTHESIS_LABEL = 'Synthesis';
+
+// ANSI escape codes for terminal control
+const ANSI_MOVE_UP = '\x1b[1A';     // Move cursor up one line
+const ANSI_CLEAR_LINE = '\x1b[2K';  // Clear entire line
+
+// UI styling constants
+const SPINNER_ICON = '⠋';
+const SUMMARIZATION_SECTION_LABEL = 'Summarization';
+const COLOR_STRUCTURE = chalk.blue;      // Blue for lines and round header
+const COLOR_SPINNER = chalk.cyan;        // Cyan (lighter blue) for spinner icon
+
+// Progress state tracking
+interface ProgressState {
+  currentRound: number;
+  currentPhase: string;
+  /** Map of agent names to their list of current activities (e.g., ["proposing", "critiquing architect"]) */
+  agentActivity: Map<string, string[]>;
+  /** Map of phase keys to progress counts (e.g., "1-proposal" -> { current: 2, total: 3 }) */
+  phaseProgress: Map<string, { current: number; total: number }>;
+}
+
+/**
+ * DebateProgressUI manages the real-time progress display for debate execution.
+ * 
+ * This class provides a simple text-based progress indicator that shows:
+ * - Current round and phase
+ * - Individual agent activities
+ * - Progress counts for each phase
+ * 
+ * The UI writes to stderr to maintain separation from stdout.
+ * Output is designed to be simple and informative without complex rendering.
+ */
+export class DebateProgressUI {
+  private state: ProgressState;
+  private totalRounds: number = 0;
+  private lastOutput: string = '';
+
+  constructor() {
+    this.state = {
+      currentRound: 0,
+      currentPhase: '',
+      agentActivity: new Map<string, string[]>(),
+      phaseProgress: new Map(),
+    };
+  }
+
+  /**
+   * Initializes the progress UI with debate configuration.
+   * 
+   * @param totalRounds - Total number of rounds in the debate.
+   */
+  initialize(totalRounds: number): void {
+    this.totalRounds = totalRounds;
+  }
+
+  /**
+   * Starts the progress UI display.
+   * Must be called after initialize() and before any round/phase updates.
+   */
+  async start(): Promise<void> {
+    // Clear any previous output
+    this.clearOutput();
+  }
+
+  /**
+   * Writes a log message to stderr without leaving orphaned UI artifacts.
+   * Clears the current UI, writes the message, then redraws the UI.
+   */
+  log(message: string): void {
+    this.clearOutput();
+    const text = message.endsWith('\n') ? message : `${message}\n`;
+    writeStderr(text);
+    this.updateDisplay();
+  }
+
+  /**
+   * Signals the start of a new debate round.
+   * 
+   * @param roundNumber - The round number (1-indexed).
+   */
+  startRound(roundNumber: number): void {
+    this.state.currentRound = roundNumber;
+    this.state.currentPhase = '';
+    this.updateDisplay();
+  }
+
+  /**
+   * Signals the start of a phase within the current round.
+   * 
+   * @param phase - The phase type (proposal, critique, or refinement).
+   * @param expectedAgentCount - Expected number of agent tasks in this phase.
+   */
+  startPhase(phase: ContributionType, expectedAgentCount: number): void {
+    const phaseLabel = PHASE_LABELS[phase];
+    this.state.currentPhase = phaseLabel;
+    const phaseKey = `${this.state.currentRound}-${phase}`;
+    this.state.phaseProgress.set(phaseKey, { current: 0, total: expectedAgentCount });
+    this.state.agentActivity.clear();
+    this.updateDisplay();
+  }
+
+  /**
+   * Signals that an agent has started an activity.
+   * 
+   * @param agentName - The name of the agent.
+   * @param activity - Description of the activity (e.g., "proposing", "critiquing architect"). Multiple activities per agent are supported.
+   */
+  startAgentActivity(agentName: string, activity: string): void {
+    // Append activity into Map<agentName, activities[]>
+    const activities = this.state.agentActivity.get(agentName) ?? [];
+    activities.push(activity);
+    this.state.agentActivity.set(agentName, activities);
+    this.updateDisplay();
+  }
+
+  /**
+   * Signals that an agent has completed an activity.
+   * 
+   * @param agentName - The name of the agent.
+   * @param activity - Description of the activity to complete. Removes a single matching occurrence.
+   */
+  completeAgentActivity(agentName: string, activity: string): void {
+    // Remove a single occurrence of the activity from the agent's list; delete key if list becomes empty
+    const activities = this.state.agentActivity.get(agentName);
+    if (activities && activities.length > 0) {
+      const idx = activities.indexOf(activity);
+      if (idx >= 0) {
+        activities.splice(idx, 1);
+      }
+      if (activities.length === 0) {
+        this.state.agentActivity.delete(agentName);
+      } else {
+        this.state.agentActivity.set(agentName, activities);
+      }
+    }
+    
+    // Update phase progress
+    const currentPhase = this.state.currentPhase.toLowerCase();
+    const phaseType = Object.keys(PHASE_LABELS).find(
+      key => PHASE_LABELS[key as ContributionType].toLowerCase() === currentPhase
+    ) as ContributionType | undefined;
+    
+    if (phaseType) {
+      const phaseKey = `${this.state.currentRound}-${phaseType}`;
+      const progress = this.state.phaseProgress.get(phaseKey);
+      if (progress) {
+        progress.current++;
+        this.state.phaseProgress.set(phaseKey, progress);
+      }
+    }
+    
+    this.updateDisplay();
+  }
+
+  /**
+   * Signals that a phase has completed.
+   * 
+   * @param _phase - The phase type that completed (reserved for future use).
+   */
+  completePhase(_phase: ContributionType): void {
+    this.state.currentPhase = '';
+    this.state.agentActivity.clear();
+    this.updateDisplay();
+  }
+
+  /**
+   * Signals the start of the synthesis phase.
+   */
+  startSynthesis(): void {
+    this.state.currentPhase = SYNTHESIS_LABEL;
+    this.state.agentActivity.clear();
+    this.updateDisplay();
+  }
+
+  /**
+   * Signals that synthesis has completed.
+   */
+  completeSynthesis(): void {
+    this.state.currentPhase = '';
+    this.updateDisplay();
+  }
+
+  /**
+   * Completes the entire progress UI.
+   * Should be called when the debate finishes.
+   */
+  async complete(): Promise<void> {
+    this.clearOutput();
+  }
+
+  /**
+   * Handles errors in the progress UI.
+   * 
+   * @param _error - The error that occurred (reserved for future use).
+   */
+  handleError(_error: Error): void {
+    // Error handling can be added here if needed
+    this.clearOutput();
+  }
+
+  /**
+   * Updates the progress display with current state.
+   */
+  private updateDisplay(): void {
+    let output = this.buildProgressText();
+    
+    // Only update if output has changed
+    if (output !== this.lastOutput) {
+      this.clearOutput();
+      writeStderr(output);
+      this.lastOutput = output;
+    }
+  }
+
+  /**
+   * Builds the progress text from current state.
+   */
+  private buildProgressText(): string {
+    if (this.state.currentRound === 0) {
+      return '';
+    }
+
+    const lines: string[] = [];
+    
+    // Round progress with blue color
+    lines.push(COLOR_STRUCTURE(`┌─ Round ${this.state.currentRound}/${this.totalRounds}`));
+    
+    // Current phase
+    if (this.state.currentPhase) {
+      const currentPhase = this.state.currentPhase.toLowerCase();
+      const phaseType = Object.keys(PHASE_LABELS).find(
+        key => PHASE_LABELS[key as ContributionType].toLowerCase() === currentPhase
+      ) as ContributionType | undefined;
+      
+      let phaseText = `${this.state.currentPhase}`;
+      
+      if (phaseType) {
+        const phaseKey = `${this.state.currentRound}-${phaseType}`;
+        const progress = this.state.phaseProgress.get(phaseKey);
+        if (progress) {
+          phaseText += ` (${progress.current}/${progress.total})`;
+        }
+      }
+      
+      lines.push(COLOR_STRUCTURE('│  ') + phaseText);
+      
+      // Active agent activities with colored spinner
+      if (this.state.agentActivity.size > 0) {
+        // Map.forEach callback receives (value, key) = (activities[], agentName)
+        this.state.agentActivity.forEach((activities, agentName) => {
+          activities.forEach((activity) => {
+            lines.push(COLOR_STRUCTURE('│  ') + COLOR_SPINNER(SPINNER_ICON) + ` ${agentName} ${activity}...`);
+          });
+        });
+      }
+    } else if (this.state.agentActivity.size > 0) {
+      // No active phase, but there are activities (e.g., summarization)
+      lines.push(COLOR_STRUCTURE('│  ') + SUMMARIZATION_SECTION_LABEL);
+      this.state.agentActivity.forEach((activities, agentName) => {
+        activities.forEach((activity) => {
+          lines.push(COLOR_STRUCTURE('│  ') + COLOR_SPINNER(SPINNER_ICON) + ` ${agentName} ${activity}...`);
+        });
+      });
+    }
+    
+    lines.push(COLOR_STRUCTURE('└─'));
+    
+    // Return with newline at end so cursor is on next line
+    return lines.join('\n') + '\n';
+  }
+
+  /**
+   * Clears the previous output from the terminal.
+   */
+  private clearOutput(): void {
+    if (this.lastOutput) {
+      // Count lines in last output (number of newlines = number of lines)
+      const lineCount = (this.lastOutput.match(/\n/g) || []).length;
+      
+      // Move cursor up and clear each line
+      // Since output ends with \n, cursor is on empty line after content
+      // We need to clear that line first, then move up and clear each content line
+      for (let i = 0; i < lineCount; i++) {
+        writeStderr(ANSI_MOVE_UP);
+        writeStderr(ANSI_CLEAR_LINE);
+      }
+      
+      this.lastOutput = '';
+    }
+  }
+}

package/src/utils/prompt-loader.ts

@@ -0,0 +1,79 @@
+import fs from 'fs';
+import path from 'path';
+import { PromptSource, PROMPT_SOURCES } from '../types/agent.types';
+import { warnUser } from '../cli/index';
+
+export type PromptResolveResult = PromptSource & { text: string };
+
+/**
+ * Reads a built-in prompt file with fallback support for different execution contexts.
+ * 
+ * This function attempts to load a prompt file from the project source directory.
+ * It first tries to resolve relative to the compiled dist/ directory (for runtime),
+ * then falls back to resolving from the project root src/ directory (for tests).
+ * If both attempts fail, it returns the provided fallback text.
+ * 
+ * @param relativePathFromSrc - Path relative to the src/ directory (e.g., 'eval/prompts/system.md')
+ * @param fallbackText - Text to return if the file cannot be read
+ * @returns The contents of the prompt file, or the fallback text if unavailable
+ */
+export function readBuiltInPrompt(relativePathFromSrc: string, fallbackText: string): string {
+  try {
+    // Primary attempt: resolve from dist/ directory (../../ climbs out of dist/utils/ back to dist/)
+    return fs.readFileSync(path.resolve(__dirname, '../../', relativePathFromSrc), 'utf-8');
+  } catch (_e1) {
+    try {
+      // Secondary attempt: resolve from project root src/ directory (useful under ts-jest)
+      return fs.readFileSync(path.resolve(process.cwd(), 'src', relativePathFromSrc), 'utf-8');
+    } catch (_e2) {
+      return fallbackText;
+    }
+  }
+}
+
+/**
+ * Resolves the system prompt text for an agent or judge, either from a specified file or from a built-in default.
+ *
+ * This function attempts to load a system prompt from a file path if provided. If the file is missing, unreadable,
+ * not a file, or empty (after trimming), it will warn the user and fall back to the provided default text.
+ * Relative file paths are resolved against the given configuration directory.
+ *
+ * @param params - An object containing:
+ *   - label:      A human-readable label for the agent/judge (used in warning messages).
+ *   - configDir:  The directory to resolve relative prompt file paths against.
+ *   - promptPath: (Optional) The path to the prompt file (absolute or relative to configDir).
+ *   - defaultText:The default prompt text to use if the file is not usable.
+ *
+ * @returns An object containing:
+ *   - text:    The resolved prompt text (from file or default).
+ *   - source:  The source of the prompt ('file' or 'built-in').
+ *   - absPath: (If source is 'file') The absolute path to the prompt file.
+ */
+export function resolvePrompt(params: { label: string; configDir: string; promptPath?: string; defaultText: string }): PromptResolveResult {
+  const { label, configDir, promptPath, defaultText } = params;
+  if (!promptPath || String(promptPath).trim().length === 0) {
+    return { text: defaultText, source: PROMPT_SOURCES.BUILT_IN };
+  }
+  const abs = path.isAbsolute(promptPath) ? promptPath : path.resolve(configDir, promptPath);
+  try {
+    if (!fs.existsSync(abs)) {
+      warnUser(`System prompt file not usable for ${label} at ${abs}. Falling back to built-in default.`);
+      return { text: defaultText, source: PROMPT_SOURCES.BUILT_IN };
+    }
+    const stat = fs.statSync(abs);
+    if (!stat.isFile()) {
+      warnUser(`System prompt file not usable for ${label} at ${abs}. Falling back to built-in default.`);
+      return { text: defaultText, source: PROMPT_SOURCES.BUILT_IN };
+    }
+    const raw = fs.readFileSync(abs, 'utf-8');
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      warnUser(`System prompt file not usable for ${label} at ${abs}. Falling back to built-in default.`);
+      return { text: defaultText, source: PROMPT_SOURCES.BUILT_IN };
+    }
+    return { text: raw, source: PROMPT_SOURCES.FILE, absPath: abs };
+  } catch (_err) {
+    warnUser(`System prompt file not usable for ${label} at ${abs}. Falling back to built-in default.`);
+    return { text: defaultText, source: PROMPT_SOURCES.BUILT_IN };
+  }
+}

package/src/utils/report-generator.ts

@@ -0,0 +1,301 @@
+import { DebateState, Contribution, CONTRIBUTION_TYPES } from '../types/debate.types';
+import { AgentConfig } from '../types/agent.types';
+
+// File-level constants to avoid magic strings and improve maintainability
+const CODE_FENCE_LANG = 'text';
+const NO_PROPOSALS_MSG = 'No proposals in this round.';
+const NO_CRITIQUES_MSG = 'No critiques in this round.';
+const NO_REFINEMENTS_MSG = 'No refinements in this round.';
+const NA_TEXT = 'N/A';
+const RIGHT_ARROW_HTML = '→';
+const UNKNOWN_LABEL = 'unknown';
+
+/**
+ * Formats a date to YYYY-MM-DD HH:mm:ss local time string.
+ * @param date - The date to format.
+ * @returns Formatted date string.
+ */
+function formatLocalTime(date: Date): string {
+  const pad = (n: number) => n.toString().padStart(2, '0');
+  const year = date.getFullYear();
+  const month = pad(date.getMonth() + 1);
+  const day = pad(date.getDate());
+  const hours = pad(date.getHours());
+  const minutes = pad(date.getMinutes());
+  const seconds = pad(date.getSeconds());
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Extracts the first non-empty line from a text string.
+ * @param text - The text to extract from.
+ * @returns The first non-empty line, or empty string if none found.
+ */
+function extractFirstLine(text: string): string {
+  const lines = text.split('\n');
+  for (const line of lines) {
+    if (line.trim().length > 0) {
+      return line.trim();
+    }
+  }
+  return '';
+}
+
+/**
+ * Formats agent configuration as a markdown table.
+ * @param agents - Array of agent configurations.
+ * @returns Markdown table string.
+ */
+function formatAgentsTable(agents: AgentConfig[]): string {
+  if (agents.length === 0) {
+    return 'No agents configured.';
+  }
+
+  // Include all defined fields as requested (omit undefined values in cells by rendering 'N/A')
+  let table = '| ID | Name | Role | Model | Provider | Temperature | Enabled | SystemPromptPath | SummaryPromptPath | Summarization |\n';
+  table += '|----|------|------|-------|----------|-------------|----------|------------------|-------------------|---------------|\n';
+
+  for (const agent of agents) {
+    const id = agent.id || NA_TEXT;
+    const name = agent.name || NA_TEXT;
+    const role = agent.role || NA_TEXT;
+    const model = agent.model || NA_TEXT;
+    const provider = agent.provider || NA_TEXT;
+    const temperature = agent.temperature !== undefined ? agent.temperature.toString() : NA_TEXT;
+    const enabled = agent.enabled !== undefined ? agent.enabled.toString() : NA_TEXT;
+    const systemPromptPath = agent.systemPromptPath !== undefined ? String(agent.systemPromptPath) : NA_TEXT;
+    const summaryPromptPath = agent.summaryPromptPath !== undefined ? String(agent.summaryPromptPath) : NA_TEXT;
+    const summarization = agent.summarization !== undefined ? JSON.stringify(agent.summarization) : NA_TEXT;
+    
+    table += `| ${id} | ${name} | ${role} | ${model} | ${provider} | ${temperature} | ${enabled} | ${systemPromptPath} | ${summaryPromptPath} | ${summarization} |\n`;
+  }
+
+  return table;
+}
+
+/**
+ * Formats judge configuration as a markdown table.
+ * @param judge - Judge configuration.
+ * @returns Markdown table string.
+ */
+function formatJudgeTable(judge: AgentConfig): string {
+  // Use the same columns as agents for consistency
+  let table = '| ID | Name | Role | Model | Provider | Temperature | Enabled | SystemPromptPath | SummaryPromptPath | Summarization |\n';
+  table += '|----|------|------|-------|----------|-------------|----------|------------------|-------------------|---------------|\n';
+
+  const id = judge.id || NA_TEXT;
+  const name = judge.name || NA_TEXT;
+  const role = judge.role || NA_TEXT;
+  const model = judge.model || NA_TEXT;
+  const provider = judge.provider || NA_TEXT;
+  const temperature = judge.temperature !== undefined ? judge.temperature.toString() : NA_TEXT;
+  // Guard for optional property without unsafe cast
+  const enabled = 'enabled' in judge ? String((judge as unknown as { enabled?: unknown }).enabled) : NA_TEXT;
+  const systemPromptPath = judge.systemPromptPath !== undefined ? String(judge.systemPromptPath) : NA_TEXT;
+  const summaryPromptPath = judge.summaryPromptPath !== undefined ? String(judge.summaryPromptPath) : NA_TEXT;
+  const summarization = judge.summarization !== undefined ? JSON.stringify(judge.summarization) : NA_TEXT;
+  
+  table += `| ${id} | ${name} | ${role} | ${model} | ${provider} | ${temperature} | ${enabled} | ${systemPromptPath} | ${summaryPromptPath} | ${summarization} |\n`;
+
+  return table;
+}
+
+/**
+ * Formats contribution metadata for verbose mode.
+ * @param contribution - The contribution to format metadata for.
+ * @returns Metadata string or empty string if not verbose.
+ */
+function formatContributionMetadata(contribution: Contribution, verbose: boolean): string {
+  if (!verbose)
+    return '';
+
+  const latency = contribution.metadata.latencyMs !== undefined  ? contribution.metadata.latencyMs.toString()  : NA_TEXT;
+  const tokens = contribution.metadata.tokensUsed !== undefined  ? contribution.metadata.tokensUsed.toString()  : NA_TEXT;
+
+  return ` (latency=${latency}ms, tokens=${tokens})`;
+}
+
+/**
+ * Structured representation of a contribution formatted for markdown output.
+ */
+type FormattedContribution = { title: string; content: string };
+
+/**
+ * Formats proposals for a round.
+ * @param contributions - Array of proposal contributions.
+ * @param verbose - Whether to include metadata.
+ * @returns Array of formatted proposal entries with title and content.
+ */
+function formatProposals(contributions: Contribution[], verbose: boolean): FormattedContribution[] {
+  const proposals = contributions.filter(c => c.type === CONTRIBUTION_TYPES.PROPOSAL);
+  
+  if (proposals.length === 0) {
+    return [];
+  }
+
+  const result: FormattedContribution[] = [];
+  for (const proposal of proposals) {
+    const metadata = formatContributionMetadata(proposal, verbose);
+    result.push({
+      title: `Agent *${proposal.agentId}*${metadata}:`,
+      content: proposal.content
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Formats critiques for a round.
+ * @param contributions - Array of critique contributions.
+ * @param verbose - Whether to include metadata.
+ * @returns Array of formatted critique entries with title and content.
+ */
+function formatCritiques(contributions: Contribution[], verbose: boolean): FormattedContribution[] {
+  const critiques = contributions.filter(c => c.type === CONTRIBUTION_TYPES.CRITIQUE);
+  
+  if (critiques.length === 0) {
+    return [];
+  }
+
+  const result: FormattedContribution[] = [];
+  for (const critique of critiques) {
+    const metadata = formatContributionMetadata(critique, verbose);
+    const target = critique.targetAgentId || UNKNOWN_LABEL;
+    result.push({
+      title: `*${critique.agentId}* ${RIGHT_ARROW_HTML} *${target}*${metadata}:`,
+      content: critique.content
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Formats refinements for a round.
+ * @param contributions - Array of refinement contributions.
+ * @param verbose - Whether to include metadata.
+ * @returns Array of formatted refinement entries with title and content.
+ */
+function formatRefinements(contributions: Contribution[], verbose: boolean): FormattedContribution[] {
+  const refinements = contributions.filter(c => c.type === CONTRIBUTION_TYPES.REFINEMENT);
+  
+  if (refinements.length === 0) {
+    return [];
+  }
+
+  const result: FormattedContribution[] = [];
+  for (const refinement of refinements) {
+    const metadata = formatContributionMetadata(refinement, verbose);
+    result.push({
+      title: `Agent *${refinement.agentId}*${metadata}:`,
+      content: refinement.content
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Renders a contribution section with a heading, titles outside code fences, and fenced content.
+ * Extracted to remove repetition across proposals, critiques, and refinements.
+ * @param heading - The section heading label.
+ * @param items - The list of formatted contributions.
+ * @param emptyMessage - Message to display when there are no items.
+ */
+function renderContributionSection(
+  heading: string,
+  items: FormattedContribution[],
+  emptyMessage: string
+): string {
+  let section = `#### ${heading}\n`;
+  if (items.length === 0) {
+    section += `${emptyMessage}\n\n`;
+    return section;
+  }
+  for (const item of items) {
+    section += `${item.title}\n`;
+    section += `\`\`\`${CODE_FENCE_LANG}\n${item.content}\n\`\`\`\n\n`;
+  }
+  return section;
+}
+
+/**
+ * Generates a complete debate report in markdown format.
+ * @param debateState - The complete debate state.
+ * @param agentConfigs - Array of agent configurations.
+ * @param judgeConfig - Judge configuration.
+ * @param problemDescription - The full problem description text.
+ * @param options - Options including verbose flag.
+ * @returns Complete markdown report string.
+ */
+export function generateDebateReport(
+  debateState: DebateState,
+  agentConfigs: AgentConfig[],
+  judgeConfig: AgentConfig,
+  problemDescription: string,
+  options: { verbose?: boolean }
+): string {
+  const title = extractFirstLine(problemDescription);
+  const time = formatLocalTime(debateState.createdAt);
+  const verbose = options.verbose || false;
+
+  let report = `# Debate: ${title}\n`;
+  report += `Time: ${time}\n\n`;
+
+  // Problem Description section
+  report += `## Problem Description\n`;
+  report += `\`\`\`text\n${problemDescription}\n\`\`\`\n\n`;
+
+  // Agents section
+  report += `## Agents\n\n`;
+  report += formatAgentsTable(agentConfigs);
+  report += `\n\n`;
+
+  // Clarifications section (if any)
+  if (debateState.clarifications && debateState.clarifications.length > 0) {
+    report += `## Clarifications\n\n`;
+    for (const group of debateState.clarifications) {
+      report += `### ${group.agentName} (${group.role})\n`;
+      for (const item of group.items) {
+        report += `Question (${item.id}):\n\n\`\`\`${CODE_FENCE_LANG}\n${item.question}\n\`\`\`\n\n`;
+        report += `Answer:\n\n\`\`\`${CODE_FENCE_LANG}\n${item.answer}\n\`\`\`\n\n`;
+      }
+    }
+    report += `\n`;
+  }
+
+  // Judge section
+  report += `## Judge\n\n`;
+  report += formatJudgeTable(judgeConfig);
+  report += `\n\n`;
+
+  // Rounds section
+  report += `## Rounds\n\n`;
+
+  for (const round of debateState.rounds) {
+    report += `### Round ${round.roundNumber}\n\n`;
+
+    // Proposals
+    const formattedProposals = formatProposals(round.contributions, verbose);
+    report += renderContributionSection('Proposals', formattedProposals, NO_PROPOSALS_MSG);
+
+    // Critiques
+    const formattedCritiques = formatCritiques(round.contributions, verbose);
+    report += renderContributionSection('Critiques', formattedCritiques, NO_CRITIQUES_MSG);
+
+    // Refinements
+    const formattedRefinements = formatRefinements(round.contributions, verbose);
+    report += renderContributionSection('Refinements', formattedRefinements, NO_REFINEMENTS_MSG);
+  }
+
+  // Final Synthesis section
+  report += `### Final Synthesis\n`;
+  if (debateState.finalSolution) {
+    report += `\`\`\`text\n${debateState.finalSolution.description}\n\`\`\`\n`;
+  } else {
+    report += `\`\`\`text\nNo final solution available.\n\`\`\`\n`;
+  }
+
+  return report;
+}