@brutalist/mcp 0.8.1 → 0.9.3

package/dist/brutalist-server.js

@@ -1,32 +1,46 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { randomUUID } from "crypto";
-import express from "express";
 import { z } from "zod";
 import { CLIAgentOrchestrator } from './cli-agents.js';
 import { logger } from './logger.js';
 import { BASE_ROAST_SCHEMA } from './types/tool-config.js';
 import { TOOL_CONFIGS } from './tool-definitions-generated.js';
-import { extractPaginationParams, parseCursor, PAGINATION_DEFAULTS, ResponseChunker, createPaginationMetadata, formatPaginationStatus, estimateTokenCount } from './utils/pagination.js';
+import { parseCursor, PAGINATION_DEFAULTS } from './utils/pagination.js';
 import { ResponseCache } from './utils/response-cache.js';
+import { ResponseFormatter } from './formatting/response-formatter.js';
+import { HttpTransport } from './transport/http-transport.js';
+import { ToolHandler } from './handlers/tool-handler.js';
 // Use environment variable or fallback to manual version
 const PACKAGE_VERSION = process.env.npm_package_version || "0.6.12";
+/**
+ * BrutalistServer - Composition root for the Brutalist MCP Server
+ *
+ * This class has been refactored to follow the Single Responsibility Principle.
+ * Responsibilities are now delegated to specialized modules:
+ * - ResponseFormatter: Handles all response formatting and pagination
+ * - HttpTransport: Manages HTTP server and CORS
+ * - ToolHandler: Handles roast tool execution, caching, and conversation continuation
+ */
 export class BrutalistServer {
     server;
     config;
+    // Core dependencies
     cliOrchestrator;
-    httpTransport;
     responseCache;
-    actualPort;
-    httpServer; // Store HTTP server reference for proper cleanup
-    shutdownHandler;
+    // Extracted modules
+    formatter;
+    toolHandler;
+    httpTransport;
     // Session tracking for security
     activeSessions = new Map();
+    // Session cleanup configuration
+    MAX_SESSIONS = 10000;
+    SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+    sessionCleanupTimer;
     constructor(config = {}) {
         this.config = {
             workingDirectory: process.cwd(),
-            defaultTimeout: 1800000, // 30 minutes - complex codebases need time (configurable via BRUTALIST_TIMEOUT env)
+            defaultTimeout: 1800000, // 30 minutes - complex codebases need time
             transport: 'stdio', // Default to stdio for backward compatibility
             httpPort: 3000,
             ...config
@@ -43,20 +57,108 @@ export class BrutalistServer {
             compressionThresholdMB: 1
         });
         logger.info(`📦 Response cache initialized with ${cacheTTLHours} hour TTL`);
+        // Session cleanup timer - runs hourly
+        this.sessionCleanupTimer = setInterval(() => this.cleanupStaleSessions(), 60 * 60 * 1000);
+        this.sessionCleanupTimer.unref(); // Don't block Node.js exit
+        logger.info(`🔐 Session cleanup initialized (TTL: 24h, max: ${this.MAX_SESSIONS})`);
+        // Initialize extracted modules
+        this.formatter = new ResponseFormatter();
+        this.toolHandler = new ToolHandler(this.cliOrchestrator, this.responseCache, this.formatter, this.config, this.activeSessions, this.handleStreamingEvent, this.handleProgressUpdate, () => this.ensureSessionCapacity() // Session capacity management
+        );
+        // Initialize MCP server
         this.server = new McpServer({
             name: "brutalist-mcp",
             version: PACKAGE_VERSION
         }, {
             capabilities: {
                 tools: {},
-                logging: {},
-                experimental: {
-                    streaming: true
-                }
+                logging: {}
+                // Removed experimental.streaming - caused Zod validation errors in Claude Code client
             }
         });
         this.registerTools();
     }
+    async start() {
+        logger.info("Starting Brutalist MCP Server with CLI Agents");
+        // Skip CLI detection at startup - will be done lazily on first request
+        logger.info("CLI context will be detected on first request");
+        if (this.config.transport === 'http') {
+            await this.startHttpServer();
+        }
+        else {
+            await this.startStdioServer();
+        }
+        logger.info("Brutalist MCP Server started successfully");
+    }
+    async startStdioServer() {
+        logger.info("Starting with stdio transport");
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+    async startHttpServer() {
+        // Create and start HTTP transport
+        this.httpTransport = new HttpTransport(this.config, (transport) => {
+            // Connect MCP server to HTTP transport
+            this.server.connect(transport);
+        });
+        await this.httpTransport.start(PACKAGE_VERSION);
+    }
+    // Getter for actual listening port (useful for tests)
+    getActualPort() {
+        return this.httpTransport?.getActualPort();
+    }
+    // Stop the HTTP server gracefully
+    async stop() {
+        if (this.httpTransport) {
+            await this.httpTransport.stop();
+        }
+    }
+    /**
+     * Clean up stale sessions that exceed TTL
+     */
+    cleanupStaleSessions() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, session] of this.activeSessions) {
+            if (now - session.lastActivity > this.SESSION_TTL_MS) {
+                this.activeSessions.delete(id);
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            logger.info(`🧹 Cleaned ${cleaned} stale sessions (>${this.SESSION_TTL_MS / 3600000}h idle)`);
+        }
+    }
+    /**
+     * Ensure session capacity doesn't exceed MAX_SESSIONS
+     * Evicts oldest sessions when capacity is reached
+     */
+    ensureSessionCapacity() {
+        while (this.activeSessions.size >= this.MAX_SESSIONS) {
+            // Remove oldest session (first entry in Map)
+            const oldestKey = this.activeSessions.keys().next().value;
+            if (oldestKey) {
+                this.activeSessions.delete(oldestKey);
+                logger.debug(`♻️ Evicted oldest session to maintain capacity`);
+            }
+            else {
+                break;
+            }
+        }
+    }
+    // Cleanup method for tests - remove event listeners
+    cleanup() {
+        if (this.httpTransport) {
+            this.httpTransport.cleanup();
+        }
+        if (this.sessionCleanupTimer) {
+            clearInterval(this.sessionCleanupTimer);
+            this.sessionCleanupTimer = undefined;
+        }
+    }
+    /**
+     * Handle streaming events from CLI agents
+     */
     handleStreamingEvent = (event) => {
         try {
             if (!event.sessionId) {
@@ -65,10 +167,9 @@ export class BrutalistServer {
             }
             logger.debug(`🔄 Session-scoped streaming: ${event.type} from ${event.agent} to session ${event.sessionId.substring(0, 8)}...`);
             // For HTTP transport: send session-specific notification if client supports it
-            if (this.httpTransport) {
+            const httpTransportInstance = this.httpTransport?.getTransport();
+            if (httpTransportInstance) {
                 try {
-                    // Debug: Check what capabilities the server has
-                    logger.debug(`🔍 Server capabilities check: logging=${!!this.server.server._capabilities?.logging}`);
                     // Use MCP server's notification system with session context
                     this.server.server.notification({
                         method: "notifications/message",
@@ -122,6 +223,9 @@ export class BrutalistServer {
             });
         }
     };
+    /**
+     * Handle progress updates from CLI agents
+     */
     handleProgressUpdate = (progressToken, progress, total, message, sessionId) => {
         try {
             if (!sessionId) {
@@ -155,164 +259,9 @@ export class BrutalistServer {
             });
         }
     };
-    async start() {
-        logger.info("Starting Brutalist MCP Server with CLI Agents");
-        // Skip CLI detection at startup - will be done lazily on first request
-        logger.info("CLI context will be detected on first request");
-        if (this.config.transport === 'http') {
-            await this.startHttpServer();
-        }
-        else {
-            await this.startStdioServer();
-        }
-        logger.info("Brutalist MCP Server started successfully");
-    }
-    async startStdioServer() {
-        logger.info("Starting with stdio transport");
-        const transport = new StdioServerTransport();
-        await this.server.connect(transport);
-    }
-    async startHttpServer() {
-        logger.info(`Starting with HTTP streaming transport on port ${this.config.httpPort}`);
-        // Create HTTP transport with streaming support
-        this.httpTransport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            enableJsonResponse: false, // Force SSE streaming
-            onsessioninitialized: (sessionId) => {
-                logger.info(`New session initialized: ${sessionId}`);
-            },
-            onsessionclosed: (sessionId) => {
-                logger.info(`Session closed: ${sessionId}`);
-            }
-        });
-        // Connect the MCP server to the HTTP transport
-        await this.server.connect(this.httpTransport);
-        // Create Express app for HTTP handling
-        const app = express();
-        app.use(express.json({ limit: '10mb' })); // Add JSON size limit for security
-        // Secure CORS implementation
-        app.use((req, res, next) => {
-            const origin = req.headers.origin;
-            const isProduction = process.env.NODE_ENV === 'production';
-            // Define safe default origins for development
-            const defaultDevOrigins = [
-                'http://localhost:3000',
-                'http://127.0.0.1:3000',
-                'http://localhost:8080',
-                'http://127.0.0.1:8080',
-                'http://localhost:3001',
-                'http://127.0.0.1:3001'
-            ];
-            // Get allowed origins from config or use defaults
-            const allowedOrigins = this.config.corsOrigins || defaultDevOrigins;
-            const allowWildcard = this.config.allowCORSWildcard === true && !isProduction;
-            // Determine if origin is allowed
-            let allowedOrigin = null;
-            if (allowWildcard) {
-                // Only in development with explicit opt-in
-                allowedOrigin = '*';
-                logger.warn("⚠️ Using wildcard CORS - only safe in development!");
-            }
-            else if (!origin) {
-                // No origin header (same-origin or direct server access)
-                allowedOrigin = defaultDevOrigins[0]; // Default fallback
-            }
-            else if (allowedOrigins.includes(origin)) {
-                // Explicitly allowed origin
-                allowedOrigin = origin;
-            }
-            else {
-                // Rejected origin
-                logger.warn(`🚫 CORS rejected origin: ${origin}`);
-                allowedOrigin = null;
-            }
-            // Set headers only if origin is allowed
-            if (allowedOrigin) {
-                res.header('Access-Control-Allow-Origin', allowedOrigin);
-                res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-                res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
-                // Removed Authorization header for security
-                res.header('Access-Control-Allow-Credentials', 'false'); // Explicit false
-            }
-            if (req.method === 'OPTIONS') {
-                if (allowedOrigin) {
-                    res.sendStatus(200);
-                }
-                else {
-                    res.sendStatus(403); // Forbidden for disallowed origins
-                }
-                return;
-            }
-            next();
-        });
-        // Route all MCP requests through the transport
-        app.all('/mcp', async (req, res) => {
-            try {
-                await this.httpTransport.handleRequest(req, res, req.body);
-            }
-            catch (error) {
-                logger.error("HTTP request handling failed", error);
-                if (!res.headersSent) {
-                    res.status(500).json({ error: 'Internal server error' });
-                }
-            }
-        });
-        // Health check endpoint
-        app.get('/health', (req, res) => {
-            res.json({ status: 'ok', transport: 'http-streaming', version: PACKAGE_VERSION });
-        });
-        // Start the HTTP server - bind to localhost only for security
-        const port = this.config.httpPort ?? 3000;
-        return new Promise((resolve, reject) => {
-            this.httpServer = app.listen(port, '127.0.0.1', () => {
-                const actualPort = this.httpServer.address()?.port || port;
-                this.actualPort = actualPort;
-                logger.info(`HTTP server listening on port ${actualPort}`);
-                logger.info(`MCP endpoint: http://localhost:${actualPort}/mcp`);
-                logger.info(`Health check: http://localhost:${actualPort}/health`);
-                resolve();
-            });
-            this.httpServer.on('error', (error) => {
-                logger.error('HTTP server failed to start', error);
-                reject(error);
-            });
-            // Handle graceful shutdown - avoid duplicate listeners
-            if (!this.shutdownHandler) {
-                this.shutdownHandler = () => {
-                    logger.info('Received SIGTERM, shutting down gracefully');
-                    this.httpServer?.close(() => {
-                        logger.info('HTTP server closed');
-                        process.exit(0);
-                    });
-                };
-                process.on('SIGTERM', this.shutdownHandler);
-            }
-        });
-    }
-    // Getter for actual listening port (useful for tests)
-    getActualPort() {
-        return this.actualPort;
-    }
-    // Stop the HTTP server gracefully
-    async stop() {
-        if (this.httpServer) {
-            return new Promise((resolve) => {
-                this.httpServer.close(() => {
-                    logger.info('HTTP server stopped');
-                    this.httpServer = undefined;
-                    this.actualPort = undefined;
-                    resolve();
-                });
-            });
-        }
-    }
-    // Cleanup method for tests - remove event listeners
-    cleanup() {
-        if (this.shutdownHandler) {
-            process.removeListener('SIGTERM', this.shutdownHandler);
-            this.shutdownHandler = undefined;
-        }
-    }
+    /**
+     * Register all MCP tools
+     */
     registerTools() {
         // Register all roast tools using unified handler - DRY principle
         TOOL_CONFIGS.forEach(config => {
@@ -320,11 +269,14 @@ export class BrutalistServer {
                 ...config.schemaExtensions,
                 ...BASE_ROAST_SCHEMA
             };
-            this.server.tool(config.name, config.description, schema, async (args, extra) => this.handleRoastTool(config, args, extra));
+            this.server.tool(config.name, config.description, schema, async (args, extra) => this.toolHandler.handleRoastTool(config, args, extra));
         });
         // Register special tools that don't follow the pattern
         this.registerSpecialTools();
     }
+    /**
+     * Register special tools (debate, roster)
+     */
     registerSpecialTools() {
         // ROAST_CLI_DEBATE: Adversarial analysis between different CLI agents
         this.server.tool("roast_cli_debate", "Deploy CLI agents in structured adversarial debate. Agents take opposing positions and systematically challenge each other's reasoning. Perfect for exploring complex topics from multiple perspectives and stress-testing ideas through rigorous intellectual discourse.", {
@@ -333,10 +285,18 @@ export class BrutalistServer {
             context: z.string().optional().describe("Additional context for the debate"),
             workingDirectory: z.string().optional().describe("Working directory for analysis"),
             models: z.object({
-                claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
-                codex: z.string().optional().describe("Codex model: gpt-5.1-codex-max (latest), gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5-codex, gpt-5, o4-mini"),
-                gemini: z.string().optional().describe("Gemini model: gemini-3-pro-preview (latest), gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite")
-            }).optional().describe("Specific models to use for each CLI agent")
+                claude: z.string().optional().describe("Claude model: opus (recommended), sonnet, haiku, opusplan, or full name like claude-opus-4-5-20251101. Default: user's configured model"),
+                codex: z.string().optional().describe("Codex model: gpt-5.1-codex-max (recommended), gpt-5.2, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5-codex, o4-mini. Default: CLI's default"),
+                gemini: z.string().optional().describe("Gemini model: gemini-3-pro (recommended), gemini-3-flash, gemini-2.5-pro, gemini-2.5-flash. Default: Auto routing")
+            }).optional().describe("Specific models to use for each CLI agent - defaults let each CLI use its own latest model"),
+            // Pagination and continuation parameters
+            context_id: z.string().optional().describe("Context ID from previous response for pagination or conversation continuation"),
+            resume: z.boolean().optional().describe("Continue debate with history injection (requires context_id)"),
+            offset: z.number().min(0).optional().describe("Pagination offset"),
+            limit: z.number().min(1000).max(100000).optional().describe("Max chars/chunk (default: 90000)"),
+            cursor: z.string().optional().describe("Pagination cursor"),
+            force_refresh: z.boolean().optional().describe("Ignore cache"),
+            verbose: z.boolean().optional().describe("Detailed output")
         }, async (args) => {
             // CRITICAL: Prevent recursion
             if (process.env.BRUTALIST_SUBPROCESS === '1') {
@@ -348,11 +308,7 @@ export class BrutalistServer {
                         }]
                 };
             }
-            return this.handleToolExecution(async () => {
-                const debateRounds = Math.min(args.debateRounds || 2, 10); // Limit to max 10 rounds to prevent DoS
-                const responses = await this.executeCLIDebate(args.targetPath, debateRounds, args.context, args.workingDirectory, args.models);
-                return responses;
-            });
+            return this.handleDebateToolExecution(args);
         });
         // CLI_AGENT_ROSTER: Show available brutalist critics
         this.server.tool("cli_agent_roster", "Know your weapons. Display the available CLI agent critics (Claude Code, Codex, Gemini CLI) ready to demolish your work, their capabilities, and how to deploy them for systematic destruction.", {}, async (args) => {
@@ -383,12 +339,16 @@ export class BrutalistServer {
                 const cliContext = await this.cliOrchestrator.detectCLIContext();
                 roster += "## Current CLI Context\n";
                 roster += `**Available CLIs:** ${cliContext.availableCLIs.join(', ') || 'None detected'}\n\n`;
-                roster += "## Pagination Support (NEW in v0.5.2)\n";
-                roster += "**All tools now support intelligent pagination:**\n";
-                roster += "- Analysis results are cached with 2-hour TTL\n";
-                roster += "- Use `context_id` from response to resume conversation\n";
-                roster += "- Smart text chunking preserves readability\n";
-                roster += "- Example: `roast_codebase(context_id: 'a3f5c2d8', offset: 25000)`\n\n";
+                roster += "## Pagination & Conversation Continuation\n";
+                roster += "**Two distinct modes for using context_id:**\n\n";
+                roster += "**1. Pagination** (cached result retrieval):\n";
+                roster += "- `context_id` alone returns cached response at different offsets\n";
+                roster += "- Example: `roast_codebase(context_id: 'abc123', offset: 25000)`\n\n";
+                roster += "**2. Conversation Continuation** (resume dialogue with history):\n";
+                roster += "- `context_id` + `resume: true` + new content continues the conversation\n";
+                roster += "- Prior conversation is injected into CLI agent context\n";
+                roster += "- Example: `roast_codebase(context_id: 'abc123', resume: true, content: 'Explain issue #3 in detail')`\n\n";
+                roster += "**Cache TTL:** 2 hours\n\n";
                 roster += "## Brutalist Philosophy\n";
                 roster += "*All tools use CLI agents with brutal system prompts for maximum reality-based criticism.*\n";
                 return {
@@ -396,84 +356,53 @@ export class BrutalistServer {
                 };
             }
             catch (error) {
-                return this.formatErrorResponse(error);
+                return this.formatter.formatErrorResponse(error);
             }
         });
     }
     /**
-     * Unified handler for all roast tools - DRY principle
+     * Handle debate tool execution with caching, pagination, and conversation continuation
+     * Delegated mostly to ToolHandler but kept here for CLI debate-specific logic
      */
-    async handleRoastTool(config, args, extra) {
+    async handleDebateToolExecution(args) {
         try {
-            // CRITICAL: Prevent recursion - reject tool calls from brutalist-spawned subprocesses
-            if (process.env.BRUTALIST_SUBPROCESS === '1') {
-                logger.warn(`🚫 Rejecting tool call from brutalist subprocess (recursion prevented)`);
-                return {
-                    content: [{
-                            type: "text",
-                            text: `ERROR: Brutalist MCP tools cannot be used from within a brutalist-spawned CLI subprocess (recursion prevented)`
-                        }]
-                };
-            }
-            const progressToken = extra._meta?.progressToken;
-            // Extract session context for security
-            // IMPORTANT: Use consistent "anonymous" for all anonymous users to enable cache sharing
-            const sessionId = extra?.sessionId ||
-                extra?._meta?.sessionId ||
-                extra?.headers?.['mcp-session-id'] ||
-                'anonymous'; // Consistent for cache sharing across pagination requests
-            const requestId = `${sessionId}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
-            logger.debug(`🔐 Processing request with session: ${sessionId.substring(0, 8)}..., request: ${requestId.substring(0, 12)}...`);
-            // Track session activity
-            if (!this.activeSessions.has(sessionId)) {
-                this.activeSessions.set(sessionId, {
-                    startTime: Date.now(),
-                    requestCount: 0,
-                    lastActivity: Date.now()
-                });
-            }
-            const sessionInfo = this.activeSessions.get(sessionId);
-            sessionInfo.requestCount++;
-            sessionInfo.lastActivity = Date.now();
-            logger.debug(`Tool execution: ${config.name}, primaryArgField=${config.primaryArgField}`);
-            logger.debug(`Args: ${JSON.stringify(args, null, 2)}`);
-            // Extract pagination parameters
-            const paginationParams = extractPaginationParams(args);
+            // Build pagination params
+            const paginationParams = {
+                offset: args.offset || 0,
+                limit: args.limit || PAGINATION_DEFAULTS.DEFAULT_LIMIT_TOKENS
+            };
             if (args.cursor) {
                 const cursorParams = parseCursor(args.cursor);
                 Object.assign(paginationParams, cursorParams);
             }
-            // Determine if pagination was explicitly requested by the user
             const explicitPaginationRequested = args.offset !== undefined ||
                 args.limit !== undefined ||
                 args.cursor !== undefined ||
                 args.context_id !== undefined;
-            logger.info(`🔧 DEBUG: explicitPaginationRequested=${explicitPaginationRequested}, offset=${args.offset}, limit=${args.limit}, cursor=${args.cursor}, context_id=${args.context_id}`);
-            // Check cache if context_id provided - detect conversation continuation
+            // Validate resume flag requires context_id
+            if (args.resume && !args.context_id) {
+                throw new Error(`The 'resume' flag requires a 'context_id' from a previous debate. ` +
+                    `Run an initial debate first, then use the returned context_id with resume: true.`);
+            }
+            // Check cache if context_id provided
             let conversationHistory;
             if (args.context_id && !args.force_refresh) {
-                const cachedResponse = await this.responseCache.getByContextId(args.context_id, sessionId);
+                const cachedResponse = await this.responseCache.getByContextId(args.context_id);
                 if (cachedResponse) {
-                    logger.info(`🎯 Cache HIT for context_id: ${args.context_id}`);
-                    // Check if this is a continuation (new user prompt provided)
-                    // For text-based tools, check 'content' field; for filesystem tools, check primaryArgField
-                    const textContent = args.content || args.idea || args.architecture || args.research || args.product || args.security || args.infrastructure;
-                    const primaryArg = textContent || args[config.primaryArgField];
-                    // Check if content is different from the last message in conversation history
-                    const lastUserMessage = cachedResponse.conversationHistory
-                        ?.filter(msg => msg.role === 'user')
-                        .pop();
-                    const isDifferentContent = !lastUserMessage || (primaryArg && primaryArg.trim() !== lastUserMessage.content.trim());
-                    const hasNewUserPrompt = primaryArg && primaryArg.trim() !== '' && isDifferentContent;
-                    if (hasNewUserPrompt) {
-                        // CONVERSATION CONTINUATION: User is adding a new prompt to the thread
-                        logger.info(`💬 Detected conversation continuation - new prompt: "${primaryArg.substring(0, 50)}..."`);
+                    logger.info(`🎯 Debate cache HIT for context_id: ${args.context_id}`);
+                    if (args.resume === true) {
+                        // CONVERSATION CONTINUATION: Continue the debate
+                        if (!args.targetPath || args.targetPath.trim() === '') {
+                            throw new Error(`Debate continuation (resume: true) requires a new prompt/question. ` +
+                                `Provide your follow-up in the targetPath field.`);
+                        }
+                        logger.info(`💬 Debate continuation - new prompt: "${args.targetPath.substring(0, 50)}..."`);
                         conversationHistory = cachedResponse.conversationHistory || [];
-                        // Don't return cached - fall through to execute new analysis with history
+                        // Fall through to execute new debate round with history
                     }
                     else {
-                        // PAGINATION: Just retrieving previous response (no new prompt)
-                        logger.info(`📖 Pagination request - returning cached response`);
+                        // PAGINATION: Return cached debate result
+                        logger.info(`📖 Debate pagination request - returning cached response`);
                         const cachedResult = {
                             success: true,
                             responses: [{
@@ -483,33 +412,33 @@ export class BrutalistServer {
                                     executionTime: 0
                                 }]
                         };
-                        return this.formatToolResponse(cachedResult, args.verbose, paginationParams, args.context_id, explicitPaginationRequested);
+                        return this.formatter.formatToolResponse(cachedResult, args.verbose, paginationParams, args.context_id, explicitPaginationRequested);
                     }
                 }
                 else {
-                    logger.warn(`❌ Cache MISS for context_id: ${args.context_id}, session: ${sessionId}`);
+                    logger.warn(`❌ Debate cache MISS for context_id: ${args.context_id}`);
                     throw new Error(`Context ID "${args.context_id}" not found in cache. ` +
                         `It may have expired (2 hour TTL) or belong to a different session. ` +
-                        `Remove context_id parameter to run a new analysis.`);
+                        `Remove context_id parameter to run a new debate.`);
                 }
             }
-            // Generate cache key for this request
-            const cacheKey = this.responseCache.generateCacheKey(config.cacheKeyFields.reduce((acc, field) => {
-                acc.tool = config.name;
-                if (args[field] !== undefined)
-                    acc[field] = args[field];
-                return acc;
-            }, {}));
-            // Check if we have a cached result (unless forcing refresh)
-            if (!args.force_refresh) {
-                const cachedContent = await this.responseCache.get(cacheKey, sessionId);
+            // Generate cache key for this debate
+            const cacheKey = this.responseCache.generateCacheKey({
+                tool: 'roast_cli_debate',
+                targetPath: args.targetPath,
+                debateRounds: args.debateRounds,
+                context: args.context,
+                models: args.models
+            });
+            // Check cache for identical request (if not resuming)
+            if (!args.force_refresh && !args.resume) {
+                const cachedContent = await this.responseCache.get(cacheKey);
                 if (cachedContent) {
-                    // Get existing context_id or create new alias
                     const existingContextId = this.responseCache.findContextIdForKey(cacheKey);
                     const contextId = existingContextId
                         ? this.responseCache.createAlias(existingContextId, cacheKey)
                         : this.responseCache.generateContextId(cacheKey);
-                    logger.info(`🎯 Cache hit for new request, using context_id: ${contextId}`);
+                    logger.info(`🎯 Debate cache hit for new request, using context_id: ${contextId}`);
                     const cachedResult = {
                         success: true,
                         responses: [{
@@ -519,72 +448,61 @@ export class BrutalistServer {
                                 executionTime: 0
                             }]
                     };
-                    return this.formatToolResponse(cachedResult, args.verbose, paginationParams, contextId, explicitPaginationRequested);
+                    return this.formatter.formatToolResponse(cachedResult, args.verbose, paginationParams, contextId, explicitPaginationRequested);
                 }
             }
-            // Build context with custom builder if available
-            let context = config.contextBuilder ? config.contextBuilder(args) : args.context;
-            // Get the primary argument (targetPath, idea, architecture, etc.)
-            // For text-based tools, use content field; for filesystem tools, use primaryArgField
-            const textContent = args.content || args.idea || args.architecture || args.research || args.product || args.security || args.infrastructure;
-            const primaryArg = textContent || args[config.primaryArgField];
-            // If we have conversation history, inject it into the context
+            // Build context with conversation history if resuming
+            let debateContext = args.context || '';
             if (conversationHistory && conversationHistory.length > 0) {
-                const conversationContext = conversationHistory.map(msg => {
-                    const role = msg.role === 'user' ? 'User' : 'Assistant';
-                    return `${role}: ${msg.content}`;
+                const previousDebate = conversationHistory.map(msg => {
+                    const role = msg.role === 'user' ? 'User Question' : 'Debate Response';
+                    return `${role}:\n${msg.content}`;
                 }).join('\n\n---\n\n');
-                const contextPrefix = `## Previous Conversation\n\n${conversationContext}\n\n---\n\n## New User Prompt\n\n`;
-                context = contextPrefix + (context || '');
-                logger.info(`💬 Injected ${conversationHistory.length} previous messages into context`);
+                debateContext = `## Previous Debate Context\n\n${previousDebate}\n\n---\n\n## New Follow-up Question\n\nThe user wants to continue this debate with a new question or direction.\n\n${debateContext}`;
+                logger.info(`💬 Injected ${conversationHistory.length} previous messages into debate context`);
             }
-            logger.debug(`Primary arg: ${config.primaryArgField}="${primaryArg}", analysisType="${config.analysisType}"`);
-            // Run the analysis
-            const result = await this.executeBrutalistAnalysis(config.analysisType, primaryArg, config.systemPrompt, context, args.workingDirectory, args.preferredCLI, args.verbose, args.models, progressToken, sessionId, requestId);
-            // Cache the result if successful
+            // Execute the debate
+            const debateRounds = Math.min(args.debateRounds || 2, 10);
+            const result = await this.executeCLIDebate(args.targetPath, debateRounds, debateContext, args.workingDirectory, args.models);
+            // Cache the result
             let contextId;
             if (result.success && result.responses.length > 0) {
-                const fullContent = this.extractFullContent(result);
+                const fullContent = this.formatter.extractFullContent(result);
                 if (fullContent) {
-                    const cacheData = config.cacheKeyFields.reduce((acc, field) => {
-                        acc.tool = config.name;
-                        if (args[field] !== undefined)
-                            acc[field] = args[field];
-                        return acc;
-                    }, {});
-                    // Build updated conversation history
                     const now = Date.now();
                     const updatedConversation = [
                         ...(conversationHistory || []),
-                        { role: 'user', content: primaryArg, timestamp: now },
+                        { role: 'user', content: args.targetPath, timestamp: now },
                         { role: 'assistant', content: fullContent, timestamp: now }
                     ];
-                    // If continuing a conversation, reuse the existing context_id
-                    if (args.context_id && conversationHistory) {
-                        // Update existing cache entry with extended conversation
-                        contextId = args.context_id; // TypeScript: we know this is defined from the if condition
-                        await this.responseCache.updateByContextId(contextId, fullContent, updatedConversation, sessionId || 'anonymous');
-                        logger.info(`✅ Updated conversation ${contextId} (now ${updatedConversation.length} messages)`);
+                    if (args.resume && args.context_id && conversationHistory) {
+                        // Update existing cache entry
+                        contextId = args.context_id;
+                        await this.responseCache.updateByContextId(contextId, fullContent, updatedConversation);
+                        logger.info(`✅ Updated debate conversation ${contextId} (now ${updatedConversation.length} messages)`);
                     }
                     else {
-                        // New conversation - create new context_id
-                        const { contextId: newId } = await this.responseCache.set(cacheData, fullContent, cacheKey, sessionId, requestId, updatedConversation);
+                        // New debate - create new context_id
+                        const { contextId: newId } = await this.responseCache.set({ tool: 'roast_cli_debate', targetPath: args.targetPath }, fullContent, cacheKey, undefined, undefined, updatedConversation);
                         contextId = newId;
-                        logger.info(`✅ Cached new conversation with context ID: ${contextId} for session: ${sessionId?.substring(0, 8)}`);
+                        logger.info(`✅ Cached new debate with context ID: ${contextId}`);
                     }
                 }
             }
-            return this.formatToolResponse(result, args.verbose, paginationParams, contextId, explicitPaginationRequested);
+            return this.formatter.formatToolResponse(result, args.verbose, paginationParams, contextId, explicitPaginationRequested);
         }
         catch (error) {
-            return this.formatErrorResponse(error);
+            return this.formatter.formatErrorResponse(error);
         }
     }
+    /**
+     * Execute CLI debate (kept in server for debate-specific logic)
+     */
     async executeCLIDebate(targetPath, debateRounds, context, workingDirectory, models) {
         logger.debug("Executing CLI debate", {
             targetPath,
             debateRounds,
-            workingDirectory,
+            workingDirectory
         });
         try {
             // Get CLI context
@@ -641,13 +559,6 @@ Remember: You are ${agent.toUpperCase()}, the passionate champion of ${position.
             // Subsequent rounds: Turn-based responses attacking specific arguments
             for (let round = 2; round <= debateRounds; round++) {
                 logger.debug(`Starting debate round ${round}: Adversarial engagement`);
-                // Build confrontational context from ALL previous responses
-                const previousPositions = Array.from(fullDebateTranscript.entries())
-                    .map(([agent, outputs]) => {
-                    const latestOutput = outputs[outputs.length - 1];
-                    return `${agent.toUpperCase()} argued:\n${latestOutput}`;
-                })
-                    .join('\n\n---\n\n');
                 // Execute turn-based responses with fixed positions
                 for (const [currentAgent, assignedPosition] of agentPositions.entries()) {
                     const opponents = Array.from(agentPositions.entries()).filter(([a, _]) => a !== currentAgent);
@@ -702,6 +613,9 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
             throw error;
         }
     }
+    /**
+     * Synthesize debate results into formatted output
+     */
     synthesizeDebate(responses, targetPath, rounds, agentPositions) {
         const successfulResponses = responses.filter(r => r.success);
         if (successfulResponses.length === 0) {
@@ -776,307 +690,5 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         }
         return synthesis;
     }
-    async executeBrutalistAnalysis(analysisType, primaryContent, systemPromptSpec, context, workingDirectory, preferredCLI, verbose, models, progressToken, sessionId, requestId) {
-        logger.info(`🏢 Starting brutalist analysis: ${analysisType}`);
-        logger.info(`🔧 DEBUG: preferredCLI=${preferredCLI}, primaryContent=${primaryContent}`);
-        logger.debug("Executing brutalist analysis", {
-            primaryContent,
-            analysisType,
-            systemPromptSpec,
-            workingDirectory,
-            preferredCLI
-        });
-        try {
-            // Get CLI context for execution summary
-            logger.info(`🔧 DEBUG: About to detect CLI context`);
-            await this.cliOrchestrator.detectCLIContext();
-            logger.info(`🔧 DEBUG: CLI context detected successfully`);
-            // Execute CLI agent analysis (single or multi-CLI based on preferences)
-            logger.info(`🔍 Executing brutalist analysis with timeout: ${this.config.defaultTimeout}ms`);
-            logger.info(`🔧 DEBUG: About to call cliOrchestrator.executeBrutalistAnalysis`);
-            const responses = await this.cliOrchestrator.executeBrutalistAnalysis(analysisType, primaryContent, systemPromptSpec, context, {
-                workingDirectory: workingDirectory || this.config.workingDirectory,
-                timeout: this.config.defaultTimeout,
-                preferredCLI,
-                analysisType: analysisType,
-                models,
-                onStreamingEvent: this.handleStreamingEvent,
-                progressToken,
-                onProgress: progressToken && sessionId ?
-                    (progress, total, message) => this.handleProgressUpdate(progressToken, progress, total, message, sessionId) : undefined,
-                sessionId,
-                requestId
-            });
-            logger.info(`🔧 DEBUG: cliOrchestrator.executeBrutalistAnalysis returned ${responses.length} responses`);
-            const successfulResponses = responses.filter(r => r.success);
-            const totalExecutionTime = responses.reduce((sum, r) => sum + r.executionTime, 0);
-            logger.info(`📊 Analysis complete: ${successfulResponses.length}/${responses.length} CLIs successful (${totalExecutionTime}ms total)`);
-            logger.info(`🔧 DEBUG: About to synthesize feedback`);
-            const synthesis = this.cliOrchestrator.synthesizeBrutalistFeedback(responses, analysisType);
-            logger.info(`🔧 DEBUG: Synthesis length: ${synthesis.length} characters`);
-            const result = {
-                success: successfulResponses.length > 0,
-                responses,
-                synthesis,
-                analysisType,
-                targetPath: primaryContent,
-                executionSummary: {
-                    totalCLIs: responses.length,
-                    successfulCLIs: successfulResponses.length,
-                    failedCLIs: responses.length - successfulResponses.length,
-                    totalExecutionTime,
-                    selectedCLI: responses.length === 1 ? responses[0].agent : undefined,
-                    selectionMethod: responses.length === 1 ? responses[0].selectionMethod : 'multi-cli'
-                }
-            };
-            logger.info(`🔧 DEBUG: Returning result with success=${result.success}`);
-            return result;
-        }
-        catch (error) {
-            logger.error("Brutalist analysis execution failed", error);
-            throw error;
-        }
-    }
-    /**
-     * Extract full content from analysis result for caching
-     */
-    extractFullContent(result) {
-        if (result.synthesis) {
-            return result.synthesis;
-        }
-        else if (result.responses && result.responses.length > 0) {
-            const successfulResponses = result.responses.filter(r => r.success);
-            if (successfulResponses.length > 0) {
-                let output = `${successfulResponses.length} AI critics have systematically demolished your work.\n\n`;
-                successfulResponses.forEach((response, index) => {
-                    output += `## Critic ${index + 1}: ${response.agent.toUpperCase()}\n`;
-                    output += `*Execution time: ${response.executionTime}ms*\n\n`;
-                    output += response.output;
-                    // Only add separator between critics, not after the last one
-                    if (index < successfulResponses.length - 1) {
-                        output += '\n\n---\n\n';
-                    }
-                });
-                return output;
-            }
-        }
-        return null;
-    }
-    formatToolResponse(result, verbose = false, paginationParams, contextId, explicitPaginationRequested = false) {
-        logger.info(`🔧 DEBUG: formatToolResponse called with synthesis length: ${result.synthesis?.length || 0}`);
-        logger.info(`🔧 DEBUG: result.success=${result.success}, responses.length=${result.responses?.length || 0}`);
-        logger.info(`🔧 DEBUG: pagination params:`, paginationParams);
-        logger.info(`🔧 DEBUG: explicitPaginationRequested=${explicitPaginationRequested}`);
-        // Get the primary content to paginate
-        let primaryContent = '';
-        if (result.synthesis) {
-            primaryContent = result.synthesis;
-            logger.info(`🔧 DEBUG: Using synthesis content (${primaryContent.length} characters)`);
-        }
-        else if (result.responses) {
-            const successfulResponses = result.responses.filter(r => r.success);
-            if (successfulResponses.length > 0) {
-                primaryContent = successfulResponses.map(r => r.output).join('\n\n---\n\n');
-                logger.info(`🔧 DEBUG: Using raw CLI output (${primaryContent.length} characters)`);
-            }
-        }
-        // Estimate token count to determine if pagination is needed
-        const estimatedTokens = estimateTokenCount(primaryContent);
-        const maxTokensWithoutPagination = 25000;
-        const needsAutoPagination = estimatedTokens > maxTokensWithoutPagination;
-        // CRITICAL: Always apply pagination if content is too large, even if not explicitly requested
-        // This prevents MCP protocol errors when response exceeds client token limits
-        if (needsAutoPagination || explicitPaginationRequested) {
-            if (needsAutoPagination && !explicitPaginationRequested) {
-                logger.info(`🔧 AUTO-PAGINATING: ${estimatedTokens} tokens exceeds ${maxTokensWithoutPagination} limit - forcing first page`);
-                // Force pagination params to show first chunk (use token-based limit)
-                const forcedParams = {
-                    offset: 0,
-                    limit: PAGINATION_DEFAULTS.DEFAULT_LIMIT_TOKENS // Use token-based limit
-                };
-                return this.formatPaginatedResponse(primaryContent, forcedParams, result, verbose, contextId);
-            }
-            else if (paginationParams) {
-                logger.info(`🔧 DEBUG: Applying pagination (explicitly requested)`);
-                return this.formatPaginatedResponse(primaryContent, paginationParams, result, verbose, contextId);
-            }
-        }
-        // Non-paginated response (only for content that fits within token limit)
-        if (primaryContent) {
-            logger.info(`🔧 DEBUG: Returning full response (${estimatedTokens} tokens < ${maxTokensWithoutPagination} limit)`);
-            // Include context_id even for non-paginated responses (for future pagination/caching)
-            let responseText = '';
-            if (contextId) {
-                responseText += `# Brutalist Analysis Results\n\n`;
-                responseText += `**🔑 Context ID:** ${contextId}\n\n`;
-                responseText += `---\n\n`;
-                responseText += primaryContent;
-            }
-            else {
-                responseText = primaryContent;
-            }
-            return {
-                content: [{
-                        type: "text",
-                        text: responseText
-                    }]
-            };
-        }
-        // Error handling - no successful content
-        let errorOutput = '';
-        if (result.responses) {
-            const failedResponses = result.responses.filter(r => !r.success);
-            if (failedResponses.length > 0) {
-                errorOutput = `❌ All CLI agents failed:\n` +
-                    failedResponses.map(r => `- ${r.agent.toUpperCase()}: ${r.error}`).join('\n');
-            }
-            else {
-                errorOutput = '❌ No CLI responses available';
-            }
-        }
-        else {
-            errorOutput = '❌ No analysis results';
-        }
-        return {
-            content: [{
-                    type: "text",
-                    text: errorOutput
-                }]
-        };
-    }
-    formatPaginatedResponse(content, paginationParams, result, verbose, contextId) {
-        // Using imported pagination utilities
-        const offset = paginationParams.offset || 0;
-        // Convert character-based limit to token-based limit (1 token ≈ 4 chars)
-        const limitChars = paginationParams.limit || PAGINATION_DEFAULTS.DEFAULT_LIMIT;
-        const limitTokens = Math.ceil(limitChars / 4); // Convert chars to tokens
-        logger.info(`🔧 DEBUG: Paginating content - offset: ${offset}, limitChars: ${limitChars}, limitTokens: ${limitTokens}, total: ${content.length} chars`);
-        // Use ResponseChunker for intelligent boundary detection (TOKEN-BASED)
-        const chunker = new ResponseChunker(limitTokens, PAGINATION_DEFAULTS.CHUNK_OVERLAP_TOKENS);
-        const chunks = chunker.chunkText(content);
-        // Find the appropriate chunk based on offset
-        let targetChunk = chunks[0]; // Default to first chunk
-        let targetChunkIndex = 0;
-        let currentOffset = 0;
-        for (let i = 0; i < chunks.length; i++) {
-            const chunk = chunks[i];
-            if (offset >= chunk.startOffset && offset < chunk.endOffset) {
-                targetChunk = chunk;
-                targetChunkIndex = i;
-                break;
-            }
-            currentOffset = chunk.endOffset;
-        }
-        const chunkContent = targetChunk.content;
-        const actualOffset = targetChunk.startOffset;
-        const endOffset = targetChunk.endOffset;
-        // Create pagination metadata using actual chunk boundaries
-        const pagination = createPaginationMetadata(content.length, paginationParams, limitTokens, chunks, targetChunkIndex);
-        const statusLine = formatPaginationStatus(pagination);
-        // Estimate token usage for user awareness
-        const chunkTokens = estimateTokenCount(chunkContent);
-        const totalTokens = estimateTokenCount(content);
-        // Format response with pagination info
-        let paginatedText = '';
-        // Add header
-        paginatedText += `# Brutalist Analysis Results\n\n`;
-        // Show pagination metadata
-        const needsPagination = pagination.totalChunks > 1 || pagination.hasMore;
-        const isFirstRequest = offset === 0;
-        // Always show context_id on first request for future pagination
-        if (isFirstRequest && contextId) {
-            paginatedText += `**🔑 Context ID:** ${contextId}\n`;
-            paginatedText += `**🔢 Token Estimate:** ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
-        }
-        if (needsPagination) {
-            paginatedText += `**📊 Pagination Status:** ${statusLine}\n`;
-            if (!isFirstRequest && contextId) {
-                paginatedText += `**🔑 Context ID:** ${contextId}\n`;
-            }
-            paginatedText += `**🔢 Token Estimate:** ~${chunkTokens.toLocaleString()} tokens (chunk) / ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
-            if (pagination.hasMore) {
-                if (contextId) {
-                    paginatedText += `**⏭️ Continue Reading:** Use \`context_id: "${contextId}", offset: ${endOffset}\`\n\n`;
-                }
-                else {
-                    paginatedText += `**⏭️ Continue Reading:** Use \`offset: ${endOffset}\` for next chunk\n\n`;
-                }
-            }
-        }
-        paginatedText += `---\n\n`;
-        // Add the actual content chunk
-        paginatedText += chunkContent;
-        // Add footer
-        if (needsPagination) {
-            paginatedText += `\n\n---\n\n`;
-            if (pagination.hasMore) {
-                paginatedText += `📖 **End of chunk ${pagination.chunkIndex}/${pagination.totalChunks}**\n`;
-                if (contextId) {
-                    paginatedText += `🔄 To continue: Include \`context_id: "${contextId}"\` with \`offset: ${endOffset}\` in next request`;
-                }
-                else {
-                    paginatedText += `🔄 To continue: Use same tool with \`offset: ${endOffset}\``;
-                }
-            }
-            else {
-                paginatedText += `✅ **Complete analysis shown** (${content.length.toLocaleString()} characters total)`;
-            }
-        }
-        // Add verbose execution details if requested
-        if (verbose && result.executionSummary) {
-            paginatedText += `\n\n### Execution Summary\n`;
-            paginatedText += `- **CLI Agents:** ${result.executionSummary.successfulCLIs}/${result.executionSummary.totalCLIs} successful\n`;
-            paginatedText += `- **Total Time:** ${result.executionSummary.totalExecutionTime}ms\n`;
-            if (result.executionSummary.selectedCLI) {
-                paginatedText += `- **Selected CLI:** ${result.executionSummary.selectedCLI}\n`;
-            }
-        }
-        logger.info(`🔧 DEBUG: Returning paginated chunk - ${chunkContent.length} chars (${chunkTokens} tokens)`);
-        return {
-            content: [{
-                    type: "text",
-                    text: paginatedText
-                }]
-        };
-    }
-    formatErrorResponse(error) {
-        logger.error("Tool execution failed", error);
-        // Sanitize error message to prevent information leakage
-        let sanitizedMessage = "Analysis failed";
-        if (error instanceof Error) {
-            // Only expose safe, generic error types
-            if (error.message.includes('timeout') || error.message.includes('Timeout')) {
-                sanitizedMessage = "Analysis timed out - try reducing scope or increasing timeout";
-            }
-            else if (error.message.includes('ENOENT') || error.message.includes('no such file')) {
-                sanitizedMessage = `DEBUG: Target path not found - Original error: ${error.message}`;
-            }
-            else if (error.message.includes('EACCES') || error.message.includes('permission denied')) {
-                sanitizedMessage = "Permission denied - check file access";
-            }
-            else if (error.message.includes('No CLI agents available')) {
-                sanitizedMessage = "No CLI agents available for analysis";
-            }
-            else {
-                // Generic message for other errors to prevent path/info leakage
-                sanitizedMessage = "Analysis failed due to internal error";
-            }
-        }
-        return {
-            content: [{
-                    type: "text",
-                    text: `Brutalist MCP Error: ${sanitizedMessage}`
-                }]
-        };
-    }
-    async handleToolExecution(handler) {
-        try {
-            const result = await handler();
-            return this.formatToolResponse(result);
-        }
-        catch (error) {
-            return this.formatErrorResponse(error);
-        }
-    }
 }
 //# sourceMappingURL=brutalist-server.js.map