dialectic 0.1.0

package/src/agents/prompts/shared.ts

@@ -0,0 +1,144 @@
+/**
+ * Shared prompt instructions for all agent roles.
+ * 
+ * This module provides consistent, well-formatted instructions that are appended
+ * to role-specific prompts to ensure uniform behavior across all agents.
+ */
+
+// Instruction type constants to avoid magic strings
+export const INSTRUCTION_TYPES = {
+  SYSTEM: 'system',
+  PROPOSAL: 'proposal', 
+  CRITIQUE: 'critique',
+  REFINEMENT: 'refinement',
+  SUMMARIZATION: 'summarization',
+  CLARIFICATION: 'clarification'
+} as const;
+
+export type InstructionType = typeof INSTRUCTION_TYPES[keyof typeof INSTRUCTION_TYPES];
+
+/**
+ * Returns shared system-level instructions for all agents.
+ * 
+ * @returns Formatted string containing shared system instructions
+ */
+export function getSharedSystemInstructions(): string {
+  // return `\n\n## General Guidelines\n\n- Avoid providing code snippets unless they are critical for explaining a delicate technical point\n- Focus on clear, concise explanations using simple language\n- Prioritize conceptual understanding over implementation details`;
+  return `## General Guidelines
+
+- Avoid code snippets unless essential to illustrate a complex technical point
+- Prioritize conceptual clarity over implementation details
+- Use clear, direct, and simple language
+- Be concise but complete — cover reasoning without unnecessary exposition
+`
+}
+
+/**
+ * Returns shared instructions for the proposal phase.
+ * 
+ * @returns Formatted string containing shared proposal instructions
+ */
+export function getSharedProposalInstructions(): string {
+  // return `\n\n## Response Guidelines\n\n- Do not provide code snippets unless critical for clarifying a delicate point\n- Focus on main components and main flows\n- Emphasize architectural decisions and design rationale\n- Keep explanations clear and well-structured`;
+  return `\n\n## Response Guidelines
+
+- Avoid code unless critical for explaining a subtle technical aspect
+- Focus on main components, data flows, and key decisions
+- Clearly justify architectural choices and trade-offs
+- Organize content under clear section headers (Overview, Components, Flow, Trade-offs)
+- Keep explanations structured and readable
+`
+}
+
+/**
+ * Returns shared instructions for the critique phase.
+ * 
+ * @returns Formatted string containing shared critique instructions
+ */
+export function getSharedCritiqueInstructions(): string {
+  // return `\n\n## Critique Guidelines\n\n- Criticize the architecture from your specialized perspective\n- Do not provide code snippets unless critical for explanation\n- Focus on key points raised in the criticized proposal, not implementation details\n- Identify strengths, weaknesses, and improvement opportunities\n- Provide constructive feedback with clear reasoning`;
+  return `\n\n## Critique Guidelines
+
+- Critique from your specialized perspective
+- Avoid code unless absolutely necessary for clarification
+- Focus on key architectural reasoning, not implementation details
+- Identify strengths, weaknesses, and improvement opportunities
+- Provide actionable, evidence-based feedback with clear reasoning
+`
+}
+
+/**
+ * Returns shared instructions for the refinement phase.
+ * 
+ * @returns Formatted string containing shared refinement instructions
+ */
+export function getSharedRefinementInstructions(): string {
+  // return `\n\n## Refinement Guidelines\n\n- Do not provide code snippets in your response\n- Focus on addressing key points raised in the critiques\n- Strengthen your solution based on valid feedback\n- Maintain your specialized perspective while incorporating improvements\n- Clearly explain how you've addressed the concerns raised`;
+  return `\n\n## Refinement Guidelines
+
+- Avoid code snippets
+- Address key concerns raised in critiques directly
+- Strengthen the solution based on valid feedback
+- Preserve your specialized focus while improving coherence and clarity
+- Explicitly explain how each major concern was resolved
+`
+}
+
+/**
+ * Returns shared instructions for the summarization phase.
+ * 
+ * @returns Formatted string containing shared summarization instructions
+ */
+export function getSharedSummarizationInstructions(): string {
+  // return `\n\n## Summary Guidelines\n\n- Maintain key points and decisions in your summary\n- Focus on your specialized perspective and main components/flows\n- Emphasize points that appear multiple times in the discussion\n- Preserve important insights and architectural decisions\n- Keep the summary concise but comprehensive`;
+  return `\n\n## Summary Guidelines
+
+- Preserve key architectural decisions, rationale, and recurring insights
+- Focus on your specialized perspective and major component interactions
+- Highlight patterns or trade-offs that appeared multiple times
+- Keep summaries concise but include all critical reasoning threads
+`
+}
+
+/**
+ * Returns shared instructions for the clarification phase.
+ * Ensures agents return only the expected JSON schema and provides
+ * consistent guidance across roles.
+ * 
+ * @returns Formatted string containing shared clarification instructions
+ */
+export function getSharedClarificationInstructions(): string {
+  return `\n\n## Clarification Guidelines\n\nRespond with ONLY JSON using this exact schema (no prose):\n{"questions":[{"text":"..."}]}\n\nIf none are needed, return {"questions":[]}.\n Prioritize questions that are most likely to improve the overall solution quality`;
+}
+
+/**
+ * Helper function to append appropriate shared instructions to a prompt.
+ * 
+ * @param prompt - The base prompt to append instructions to
+ * @param instructionType - The type of shared instructions to append
+ * @returns The prompt with shared instructions appended
+ */
+export function appendSharedInstructions(prompt: string, instructionType: InstructionType): string {
+  const sharedInstructions = getSharedInstructionsByType(instructionType);
+  return prompt + sharedInstructions;
+}
+
+/**
+ * Internal helper function to get shared instructions by type.
+ * 
+ * @param type - The instruction type
+ * @returns The appropriate shared instructions string
+ */
+function getSharedInstructionsByType(type: InstructionType): string {
+  switch (type) {
+    case INSTRUCTION_TYPES.SYSTEM: return getSharedSystemInstructions();
+    case INSTRUCTION_TYPES.PROPOSAL: return getSharedProposalInstructions();
+    case INSTRUCTION_TYPES.CRITIQUE: return getSharedCritiqueInstructions();
+    case INSTRUCTION_TYPES.REFINEMENT: return getSharedRefinementInstructions();
+    case INSTRUCTION_TYPES.SUMMARIZATION: return getSharedSummarizationInstructions();
+    case INSTRUCTION_TYPES.CLARIFICATION: return getSharedClarificationInstructions();
+    default: 
+      // This should never happen with proper TypeScript types
+      throw new Error(`Unknown instruction type: ${type}`);
+  }
+}

package/src/agents/prompts/testing-prompts.ts

@@ -0,0 +1,149 @@
+import { RolePrompts } from './prompt-types';
+import { prependContext } from '../../utils/context-formatter';
+import { appendSharedInstructions, INSTRUCTION_TYPES } from './shared';
+import type { DebateContext } from '../../types/debate.types';
+
+/**
+ * Prompts for the Testing role, specializing in quality assurance and testing strategy.
+ * 
+ * The testing expert focuses on test coverage, test strategies, quality metrics,
+ * edge cases, and testability of designs.
+ */
+export const testingPrompts: RolePrompts = {
+  systemPrompt: appendSharedInstructions(`You are an expert **software testing architect and quality engineer** specializing in designing verification strategies for complex distributed systems.
+
+Your focus areas:
+- System testability and observability
+- Functional and non-functional validation (performance, security, usability)
+- Test strategy and architecture (unit, integration, E2E, contract testing, chaos testing)
+- CI/CD integration and automated quality gates
+- Defect prevention through design clarity and boundary visibility
+
+When proposing solutions:
+- Define how the design can be verified and instrumented
+- Identify key components and interactions that require dedicated testing strategies
+- Consider how test feedback loops influence system reliability and maintainability
+
+When critiquing:
+- Identify weaknesses in testability, validation coverage, or observability
+- Assess whether the design supports automation and effective regression control
+- Recommend ways to improve testing clarity, traceability, and fault isolation`, INSTRUCTION_TYPES.SYSTEM),
+
+  proposePrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Problem to solve:
+${problem}
+
+As a testing expert, propose a comprehensive verification and testing strategy for this system.
+
+Use this structure:
+## Testability Overview
+Summarize how the architecture supports verification and observability.
+
+## Testing Strategy
+Outline test levels (unit, integration, system, end-to-end) and how they apply.
+
+## Automation Approach
+Describe automation coverage, CI/CD integration, and quality gates.
+
+## Observability & Monitoring
+Explain how metrics, logging, and tracing will support defect detection and validation.
+
+## Non-functional Testing
+Address load, resilience, security, and compliance testing approaches.
+
+## Risks & Limitations
+Identify areas that are hard to test or likely to fail silently.`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.PROPOSAL);
+  },
+
+  critiquePrompt: (proposalContent: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Review this proposal from a testing and quality engineering perspective.
+
+Proposal:
+${proposalContent}
+
+Structure your response as follows:
+## Strengths
+Identify well-defined testing strategies, observability mechanisms, and automation strengths.
+
+## Weaknesses
+Highlight unclear validation points, weak coverage, or poor observability.
+
+## Suggested Improvements
+Recommend strategies or architectural changes that improve testability and coverage.
+
+## Critical Gaps
+List major untested assumptions, missing validation flows, or areas with insufficient instrumentation.`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CRITIQUE);
+  },
+
+  refinePrompt: (originalContent: string, critiquesText: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `Original proposal:
+${originalContent}
+
+Critiques:
+${critiquesText}
+
+Refine your proposal to improve system testability, observability, and automation alignment.
+
+Use this structure:
+## Revised Testing Strategy
+Summarize the main changes to your test architecture or approach.
+
+## Changes Made
+List what was improved and why.
+
+## Expected Impact
+Explain how these changes improve verification coverage and system reliability.
+
+## Remaining Gaps
+Mention areas that remain difficult to validate or monitor.
+
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.REFINEMENT);
+  },
+
+  summarizePrompt: (content: string, maxLength: number) => {
+    const basePrompt = `You are summarizing the debate history from a testing and quality perspective.
+
+Debate history to summarize:
+${content}
+
+Summarize the discussion focusing on testability, observability, automation, and quality assurance design.
+
+Format:
+## Testing Insights
+Highlight main testing strategies, coverage areas, and observability improvements.
+
+## Major Decisions
+List key agreements or approaches on how testing will be implemented.
+
+## Remaining Gaps
+Note unresolved issues or testing challenges that remain open.
+
+Limit the summary to a maximum of ${maxLength} characters.`;
+    return appendSharedInstructions(basePrompt, INSTRUCTION_TYPES.SUMMARIZATION);
+  },
+
+  clarifyPrompt: (problem: string, context?: DebateContext, agentId?: string, includeFullHistory?: boolean) => {
+    const basePrompt = `You are preparing clarifying questions from a testing and verification perspective.
+
+Problem to clarify:
+${problem}
+
+Ask zero or more concise, high-value questions focused on:
+- Testability and validation coverage
+- Data and environment dependencies
+- Interfaces and integration points
+- Automation feasibility
+- Observability and metrics
+- Edge cases and error handling
+`;
+    const promptWithContext = prependContext(basePrompt, context, agentId, includeFullHistory);
+    return appendSharedInstructions(promptWithContext, INSTRUCTION_TYPES.CLARIFICATION);
+  },
+};
+

package/src/agents/role-based-agent.ts

@@ -0,0 +1,386 @@
+import { Agent } from '../core/agent';
+import { AgentConfig, Proposal, Critique, PromptSource, AgentRole } from '../types/agent.types';
+import { DebateContext, DebateSummary, ContextPreparationResult, CONTRIBUTION_TYPES, ClarificationQuestionsResponse } from '../types/debate.types';
+import { LLMProvider } from '../providers/llm-provider';
+import { getPromptsForRole, RolePrompts } from './prompts';
+import { ContextSummarizer, LengthBasedSummarizer } from '../utils/context-summarizer';
+import { writeStderr } from '../cli/index';
+import type { SummarizationConfig } from '../types/config.types';
+
+
+/**
+ * RoleBasedAgent is a unified AI agent implementation that supports multiple roles
+ * through a prompt-based configuration system.
+ * 
+ * Unlike the previous implementation with separate classes per role (ArchitectAgent,
+ * PerformanceAgent, SecurityAgent), this class uses a registry of role-specific prompts
+ * to guide behavior, eliminating code duplication while maintaining role-specific expertise.
+ * 
+ * Responsibilities:
+ * - Proposes solutions tailored to the agent's role (architect, performance, security, etc.)
+ * - Critiques proposals from other agents using role-specific perspectives
+ * - Refines its own proposals by incorporating feedback from other agents
+ * - Manages context summarization to handle large debate histories
+ * 
+ * The agent leverages an LLM provider to generate outputs, with prompts dynamically
+ * selected based on the agent's configured role.
+ * 
+ * Note: This class cannot be extended. Use the static `create` factory method to instantiate.
+ */
+export class RoleBasedAgent extends Agent {
+  private readonly resolvedSystemPrompt: string;
+  private readonly rolePrompts: RolePrompts;
+  public readonly promptSource?: PromptSource;
+  
+  // Summarization-related fields
+  private readonly summarizer?: ContextSummarizer;
+  private readonly summaryConfig: SummarizationConfig;
+  public readonly summaryPromptSource?: PromptSource;
+
+  private readonly resolvedClarificationPromptText?: string;
+
+  /**
+   * Private constructor to prevent direct instantiation and extension.
+   * Use the static `create` method instead.
+   * 
+   * @param config - Agent configuration, including role and model.
+   * @param provider - LLMProvider instance for LLM interactions.
+   * @param resolvedSystemPrompt - The final system prompt text this agent will use.
+   * @param promptSource - Optional provenance metadata for verbose/persistence.
+   * @param summaryConfig - Summarization configuration for this agent.
+   * @param summaryPromptSource - Optional provenance metadata for summary prompt.
+   * @param resolvedClarificationPromptText - Optional resolved clarification prompt text.
+   */
+  private constructor(  config: AgentConfig, provider: LLMProvider, resolvedSystemPrompt: string,
+                        promptSource: PromptSource | undefined, summaryConfig: SummarizationConfig,
+                        summaryPromptSource?: PromptSource, resolvedClarificationPromptText?: string )
+  {
+    super(config, provider);
+    this.resolvedSystemPrompt = resolvedSystemPrompt;
+    this.rolePrompts = getPromptsForRole(config.role);
+    this.summaryConfig = summaryConfig;
+    
+    if (promptSource !== undefined) {
+      this.promptSource = promptSource;
+    }
+
+    if (summaryPromptSource !== undefined) {
+      this.summaryPromptSource = summaryPromptSource;
+    }
+    if (resolvedClarificationPromptText !== undefined) {
+      this.resolvedClarificationPromptText = resolvedClarificationPromptText;
+    }
+    
+    // Initialize summarizer if summarization is enabled
+    if (summaryConfig.enabled) {
+      this.summarizer = new LengthBasedSummarizer(provider, {
+        model: config.model,
+        temperature: config.temperature,
+        provider: config.provider,
+      });
+    }
+  }
+
+  /**
+   * Factory method to create a new RoleBasedAgent instance.
+   * 
+   * @param config - Agent configuration, including role and model.
+   * @param provider - LLMProvider instance for LLM interactions.
+   * @param resolvedSystemPrompt - The final system prompt text this agent will use.
+   * @param promptSource - Optional provenance metadata for verbose/persistence.
+   * @param summaryConfig - Summarization configuration for this agent.
+   * @param summaryPromptSource - Optional provenance metadata for summary prompt.
+   * @param resolvedClarificationPromptText - Optional resolved clarification prompt text.
+   * @returns A new RoleBasedAgent instance configured for the specified role.
+   */
+  static create(  config: AgentConfig, provider: LLMProvider, resolvedSystemPrompt: string,
+                  promptSource: PromptSource | undefined, summaryConfig: SummarizationConfig,
+                  summaryPromptSource?: PromptSource,
+                  resolvedClarificationPromptText?: string ): RoleBasedAgent
+  {
+    return new RoleBasedAgent(  config, provider, resolvedSystemPrompt,
+                                promptSource, summaryConfig, summaryPromptSource,
+                                resolvedClarificationPromptText );
+  }
+
+  /**
+   * Returns the default system prompt for a given role.
+   * 
+   * This method allows callers to retrieve the built-in system prompt for any role
+   * without instantiating an agent. Used during prompt resolution to provide fallback
+   * prompts when custom prompt files are not available.
+   * 
+   * @param role - The agent role to get the default prompt for.
+   * @returns The default system prompt text for the specified role.
+   */
+  static defaultSystemPrompt(role: AgentRole): string {
+    const prompts = getPromptsForRole(role);
+    return prompts.systemPrompt;
+  }
+
+  /**
+   * Returns the default summary prompt for a given role.
+   * 
+   * This method allows callers to retrieve the built-in summary prompt for any role
+   * without instantiating an agent. Used during prompt resolution to provide fallback
+   * prompts when custom summary prompt files are not available.
+   * 
+   * @param role - The agent role to get the default summary prompt for.
+   * @param content - The content to summarize.
+   * @param maxLength - Maximum length for the summary.
+   * @returns The default summary prompt text for the specified role.
+   */
+  static defaultSummaryPrompt(role: AgentRole, content: string, maxLength: number): string {
+    const prompts = getPromptsForRole(role);
+    return prompts.summarizePrompt(content, maxLength);
+  }
+
+  /**
+   * Generates a comprehensive proposal for the given problem.
+   * 
+   * The proposal is tailored to the agent's role (e.g., architectural design for architects,
+   * performance optimization for performance engineers, security analysis for security experts).
+   * 
+   * @param problem - The software design problem to solve.
+   * @param context - Debate context containing history and state.
+   * @returns A Proposal object containing the agent's solution and metadata.
+   */
+  async propose(problem: string, context: DebateContext): Promise<Proposal> {
+    const system = this.resolvedSystemPrompt;
+    const user = this.rolePrompts.proposePrompt(problem, context, this.config.id, context.includeFullHistory);
+    return this.proposeImpl(context, system, user);
+  }
+
+  /**
+   * Critiques a given proposal from the agent's role-specific perspective.
+   * 
+   * Identifies strengths, weaknesses, improvements, and issues relevant to the agent's
+   * area of expertise (architecture, performance, security, etc.).
+   * 
+   * @param proposal - The proposal to critique.
+   * @param context - Debate context.
+   * @returns A Critique object containing the agent's review and metadata.
+   */
+  async critique(proposal: Proposal, context: DebateContext): Promise<Critique> {
+    const system = this.resolvedSystemPrompt;
+    const user = this.rolePrompts.critiquePrompt(proposal.content, context, this.config.id, context.includeFullHistory);
+    return this.critiqueImpl(proposal, context, system, user);
+  }
+
+  /**
+   * Refines the original proposal by addressing critiques and incorporating suggestions.
+   * 
+   * Strengthens the solution based on feedback from other agents while maintaining
+   * the agent's role-specific focus and expertise.
+   * 
+   * @param original - The original proposal to refine.
+   * @param critiques - Array of critiques to address.
+   * @param context - Debate context.
+   * @returns A new Proposal object with the refined solution and metadata.
+   */
+  async refine(original: Proposal, critiques: Critique[], context: DebateContext): Promise<Proposal> {
+    const system = this.resolvedSystemPrompt;
+    const critiquesText = critiques.map((c, i) => `Critique ${i + 1}:\n${c.content}`).join('\n\n');
+    const user = this.rolePrompts.refinePrompt(original.content, critiquesText, context, this.config.id, context.includeFullHistory);
+    return this.refineImpl(original, critiques, context, system, user);
+  }
+
+  /**
+   * Ask role-specific clarifying questions. Returns ONLY structured questions.
+   */
+  async askClarifyingQuestions(problem: string, context: DebateContext): Promise<ClarificationQuestionsResponse> {
+    const system = this.resolvedSystemPrompt;
+    let user = this.rolePrompts.clarifyPrompt(problem, context, this.config.id, context.includeFullHistory);
+    if (this.resolvedClarificationPromptText && this.resolvedClarificationPromptText.trim().length > 0) {
+      user = `${user}\n\n${this.resolvedClarificationPromptText}`;
+    }
+    const { text } = await this.callLLM(system, user);
+    try {
+      // Extract first JSON object if any extra tokens sneak in
+      const match = text.match(/\{[\s\S]*\}/);
+      const json = match ? match[0] : text;
+      const parsed = JSON.parse(json);
+      const list = Array.isArray(parsed?.questions) ? parsed.questions : [];
+      const normalized = list
+        .filter((q: any) => typeof q?.text === 'string' && q.text.trim().length > 0)
+        .map((q: any, idx: number) => ({ id: q.id || `q${idx + 1}`, text: q.text }));
+      return { questions: normalized };
+    } catch (err: any) {
+      writeStderr(`Warning: Agent ${this.config.name}: Invalid clarifications JSON. Error: ${err.message}\n`);
+      return { questions: [] };
+    }
+  }
+
+  
+  /**
+   * Iterates over all contributions in the debate history that are relevant to the agent
+   * (i.e., the agent's own proposals and refinements),
+   * applies a callback to each, and reduces the results.
+   *
+   * The notion of relevance includes:
+   *   - Proposals and refinements made by this agent
+   *
+   * @template T The type accumulated and returned by the reduction.
+   * @param context DebateContext containing the full history of rounds and contributions.
+   * @param callback Function to apply to each relevant contribution. Takes (contribution, roundNumber) and returns T.
+   * @param initialValue The initial value passed to the reducer.
+   * @param reducer Function combining accumulator and current callback result into new accumulator value.
+   * @returns The final reduction value from processing all relevant contributions.
+   */
+  private processRelevantContributions<T>(
+    context: DebateContext,
+    callback: (contribution: any, roundNumber: number) => T,
+    initialValue: T,
+    reducer: (accumulator: T, current: T) => T
+  ): T {
+    if (!context.history || context.history.length === 0) {
+      return initialValue;
+    }
+
+    const agentId = this.config.id;
+    let result = initialValue;
+
+    for (const round of context.history) {
+      for (const contribution of round.contributions) {
+        // Include agent's own proposals and refinements
+        if (
+          contribution.agentId === agentId &&
+          (contribution.type === CONTRIBUTION_TYPES.PROPOSAL ||
+            contribution.type === CONTRIBUTION_TYPES.REFINEMENT)
+        ) {
+          result = reducer(result, callback(contribution, round.roundNumber));
+        }
+        // // Include critiques received by this agent
+        // if (
+        //   contribution.type === CONTRIBUTION_TYPES.CRITIQUE &&
+        //   contribution.targetAgentId === agentId
+        // ) {
+        //   result = reducer(result, callback(contribution, round.roundNumber));
+        // }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Determines if context summarization should occur based on configuration and history size.
+   * 
+   * Summarization is triggered when:
+   * 1. Summarization is enabled in configuration
+   * 2. Debate history exists
+   * 3. Character count of agent's relevant history exceeds threshold
+   * 
+   * The character count includes:
+   * - Agent's own proposals
+   * - Critiques received by this agent
+   * - Agent's own refinements
+   * 
+   * @param context - The debate context to evaluate.
+   * @returns True if summarization should occur, false otherwise.
+   */
+  shouldSummarize(context: DebateContext): boolean {
+    // Check if summarization is enabled
+    if (!this.summaryConfig.enabled) {
+      return false;
+    }
+
+    // Check if history exists
+    if (!context.history || context.history.length === 0) {
+      return false;
+    }
+
+    // Calculate character count of agent's relevant history
+    const totalChars = this.processRelevantContributions( context, 
+                                                          (contribution) => contribution.content.length, 
+                                                          0, (sum, length) => sum + length
+    );
+
+    // Return true if total exceeds threshold
+    return totalChars >= this.summaryConfig.threshold;
+  }
+
+  /**
+   * Prepares the debate context, potentially summarizing it if needed.
+   * 
+   * This method evaluates whether summarization is necessary using `shouldSummarize()`.
+   * If summarization is not needed, returns the original context unchanged.
+   * If summarization is needed, generates a concise summary from the agent's perspective
+   * and returns a new context with the summary field populated.
+   * 
+   * On summarization errors, falls back to the original context with a warning.
+   * 
+   * @param context - The current debate context.
+   * @param roundNumber - The current round number (1-indexed).
+   * @returns The context preparation result.
+   */
+  async prepareContext(context: DebateContext, _roundNumber: number): Promise<ContextPreparationResult>
+  {
+    // Check if summarization is needed
+    if (!this.shouldSummarize(context)) {
+      return { context };
+    }
+
+    // Summarization is needed - filter history to agent's perspective
+    try {
+      if (!context.history) {
+        return { context };
+      }
+
+      // Collect relevant contributions using the helper function
+      const relevantContributions = this.processRelevantContributions(
+        context,
+        (contribution, roundNumber) => {
+          if (contribution.type === CONTRIBUTION_TYPES.CRITIQUE) {
+            return [`Round ${roundNumber} - Critique from ${contribution.agentRole}:\n${contribution.content}`];
+          } else {
+            return [`Round ${roundNumber} - ${contribution.type}:\n${contribution.content}`];
+          }
+        },
+        [] as string[],
+        (acc, contribution) => [...acc, ...contribution]
+      );
+
+      // Convert filtered history to text
+      const contentToSummarize = relevantContributions.join('\n\n---\n\n');
+
+      // Call summarizer
+      if (!this.summarizer) {
+        // Summarization is enabled but no summarizer (shouldn't happen, but handle gracefully)
+        // This is an internal error that should be logged to stderr
+        writeStderr(`Warning: Agent ${this.config.name}: Summarization enabled but no summarizer available. Using full history.\n`);
+        return { context };
+      }
+
+      // Construct the summary prompt with the content
+      const summaryPrompt = this.rolePrompts.summarizePrompt(contentToSummarize, this.summaryConfig.maxLength);
+
+      const result = await this.summarizer.summarize(
+        contentToSummarize,
+        this.config.role,
+        this.summaryConfig,
+        this.resolvedSystemPrompt,
+        summaryPrompt
+      );
+
+      // Build DebateSummary object
+      const summary: DebateSummary = {
+        agentId: this.config.id,
+        agentRole: this.config.role,
+        summary: result.summary,
+        metadata: result.metadata,
+      };
+
+      // Return original context and summary for persistence
+      // Summary will be looked up from rounds when formatting prompts
+      return { context, summary };
+    } catch (error: any) {
+      // Log error to stderr and fallback to full history
+      writeStderr(
+        `Warning: Agent ${this.config.name}: Summarization failed with error: ${error.message}. Falling back to full history.\n`
+      );
+      return { context };
+    }
+  }
+}
+