protoagent 0.0.2 → 0.0.4

package/dist/utils/conversation-compactor.js

@@ -1,6 +1,7 @@
 /**
  * Conversation history compaction utilities
  */
+import { logger } from './logger.js';
 /**
  * Provides the system prompt for the history compression process.
  * This prompt instructs the model to act as a specialized state manager,
@@ -69,14 +70,14 @@ The structure MUST be as follows:
  * Compact conversation history by creating a summary
  */
 export async function compactConversation(client, model, messages, recentMessagesToKeep = 5) {
-    console.log('\n🗜️  Compacting conversation history to manage context window...');
+    logger.consoleLog('\n🗜️  Compacting conversation history to manage context window...');
     // Keep the system message and recent messages
     const systemMessage = messages.find(m => m.role === 'system');
     const recentMessages = messages.slice(-recentMessagesToKeep);
     // Get the history to compress (excluding system and recent messages)
     const historyToCompress = messages.slice(systemMessage ? 1 : 0, -recentMessagesToKeep);
     if (historyToCompress.length === 0) {
-        console.log('   No history to compress, keeping current messages');
+        logger.consoleLog('   No history to compress, keeping current messages');
         return messages;
     }
     try {
@@ -100,7 +101,7 @@ export async function compactConversation(client, model, messages, recentMessage
         });
         const compressionSummary = response.choices[0]?.message?.content;
         if (!compressionSummary) {
-            console.log('   Failed to generate compression summary, keeping original messages');
+            logger.consoleLog('   Failed to generate compression summary, keeping original messages');
             return messages;
         }
         // Create the compressed history message
@@ -118,12 +119,12 @@ export async function compactConversation(client, model, messages, recentMessage
         compactedMessages.push(compressedMessage);
         // Add recent messages
         compactedMessages.push(...recentMessages);
-        console.log(`   ✅ Compressed ${historyToCompress.length} messages into summary`);
-        console.log(`   📝 Keeping ${recentMessages.length} recent messages`);
+        logger.consoleLog(`   ✅ Compressed ${historyToCompress.length} messages into summary`);
+        logger.consoleLog(`   📝 Keeping ${recentMessages.length} recent messages`);
         return compactedMessages;
     }
     catch (error) {
-        console.log(`   ❌ Compression failed: ${error}. Keeping original messages.`);
+        logger.consoleLog(`   ❌ Compression failed: ${error}. Keeping original messages.`);
         return messages;
     }
 }

package/dist/utils/cost-tracker.js

@@ -1,6 +1,7 @@
 /**
  * Cost tracking and token counting utilities
  */
+import { logger } from './logger.js';
 /**
  * Rough token estimation for OpenAI models
  * This is approximate - actual tokenization may vary
@@ -72,11 +73,11 @@ export function getContextInfo(messages, modelConfig) {
  * Log usage and cost information
  */
 export function logUsageInfo(usage, contextInfo, modelConfig) {
-    console.log(`💰 Usage: ${usage.inputTokens} in + ${usage.outputTokens} out = ${usage.totalTokens} tokens`);
-    console.log(`💸 Estimated cost: $${usage.estimatedCost.toFixed(6)}`);
-    console.log(`📊 Context: ${contextInfo.currentTokens}/${contextInfo.maxTokens} tokens (${contextInfo.utilizationPercentage.toFixed(1)}%)`);
+    logger.consoleLog(`💰 Usage: ${usage.inputTokens} in + ${usage.outputTokens} out = ${usage.totalTokens} tokens`);
+    logger.consoleLog(`💸 Estimated cost: $${usage.estimatedCost.toFixed(6)}`);
+    logger.consoleLog(`📊 Context: ${contextInfo.currentTokens}/${contextInfo.maxTokens} tokens (${contextInfo.utilizationPercentage.toFixed(1)}%)`);
     if (contextInfo.needsCompaction) {
-        console.log(`⚠️  Context approaching limit - automatic compaction will trigger soon`);
+        logger.consoleLog(`⚠️  Context approaching limit - automatic compaction will trigger soon`);
     }
 }
 /**

package/dist/utils/enhanced-prompt.js

@@ -0,0 +1,23 @@
+/**
+ * Enhanced prompt utility that supports both arrow key navigation + enter
+ * AND displays clear number shortcuts for faster interaction
+ */
+import inquirer from 'inquirer';
+/**
+ * Enhanced prompt that uses standard inquirer with clear number indicators
+ * Users can still use arrow keys + enter as normal, but numbers make it clear what to select
+ */
+export async function enhancedPrompt(message, choices, defaultValue) {
+    // Add instruction about keyboard shortcuts
+    const enhancedMessage = `${message}\n💡 Use arrow keys + Enter, or press the number key + Enter`;
+    const result = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'choice',
+            message: enhancedMessage,
+            choices: choices,
+            default: defaultValue
+        }
+    ]);
+    return result.choice;
+}

package/dist/utils/file-operations-approval.js

@@ -4,6 +4,8 @@
  */
 import inquirer from 'inquirer';
 import { logger } from './logger.js';
+import { UserCancellationError } from './user-cancellation.js';
+import { enhancedPrompt } from './enhanced-prompt.js';
 // Global state for approval settings
 let globalConfig = null;
 let dangerouslyAcceptAll = false;
@@ -19,113 +21,321 @@ export function setDangerouslyAcceptAllFileOps(accept) {
 }
 /**
  * Request user approval for file write/edit operations
+ * @throws {UserCancellationError} when user cancels the operation
  */
 export async function requestFileOperationApproval(context) {
-    const { operation, filePath, description, contentPreview } = context;
+    const { operation, filePath, description, contentPreview, oldContent, newContent, changeContext } = context;
     // Check if we should auto-approve
     if (dangerouslyAcceptAll) {
         logger.info(`🚀 Auto-approving (--dangerously-accept-all): ${operation} ${filePath}`);
-        return true;
+        return;
     }
     const operationType = operation === 'write' ? 'write_file' : 'edit_file';
     if (approvedOperationsForSession.has(operationType)) {
         logger.info(`🚀 Auto-approving (${operationType} approved for session): ${operation} ${filePath}`);
-        return true;
-    }
-    // Show detailed information about the operation
-    console.log(`\n🔐 File Operation Requested: ${operation.toUpperCase()}`);
-    console.log(`📁 File: ${filePath}`);
-    console.log(`📝 Description: ${description}`);
-    if (contentPreview) {
-        console.log(`\n📄 Content Preview:`);
-        const lines = contentPreview.split('\n');
-        if (lines.length > 10) {
-            console.log(lines.slice(0, 5).join('\n'));
-            console.log(`... (${lines.length - 10} more lines) ...`);
-            console.log(lines.slice(-5).join('\n'));
-        }
-        else {
-            console.log(contentPreview);
-        }
+        return;
     }
+    // Show detailed preview of the operation
+    await showOperationPreview(context);
     // Ask for user approval with enhanced options
-    const { choice } = await inquirer.prompt([
-        {
-            type: 'list',
-            name: 'choice',
-            message: 'Choose your action:',
-            choices: [
-                { name: `1. ✅ Approve this ${operation} operation`, value: 'approve' },
-                { name: `2. ✅ Approve and allow all ${operation} operations for this session`, value: 'approve_session' },
-                { name: '3. ❌ Cancel this operation', value: 'cancel' },
-                { name: '4. 📝 Show more details and decide', value: 'details' }
-            ],
-            default: 'approve'
-        }
-    ]);
+    const choice = await enhancedPrompt('Choose your action:', [
+        { name: `1. ✅ Approve this ${operation} operation`, value: 'approve' },
+        { name: `2. ✅ Approve and allow all ${operation} operations for this session`, value: 'approve_session' },
+        { name: '3. ❌ Cancel this operation', value: 'cancel' },
+        { name: '4. 📝 Show detailed analysis', value: 'details' }
+    ], 'approve');
     switch (choice) {
         case 'approve':
             logger.info(`✅ User approved: ${operation} ${filePath}`);
-            return true;
+            return;
         case 'approve_session':
             approvedOperationsForSession.add(operationType);
             logger.info(`🔓 "${operationType}" approved for session - all future ${operation} operations will auto-execute`);
             logger.info(`✅ User approved: ${operation} ${filePath}`);
-            return true;
+            return;
         case 'cancel':
             logger.info(`❌ User cancelled: ${operation} ${filePath}`);
-            return false;
+            throw new UserCancellationError(`${operation} operation on ${filePath}`, 'User chose to cancel the operation');
         case 'details':
             await showFileOperationDetails(context);
             // Recursively ask again after showing details
             return await requestFileOperationApproval(context);
         default:
             logger.info(`❌ User cancelled: ${operation} ${filePath}`);
-            return false;
+            throw new UserCancellationError(`${operation} operation on ${filePath}`, 'User did not approve the operation');
+    }
+}
+/**
+ * Show a detailed preview of the file operation before asking for approval
+ */
+async function showOperationPreview(context) {
+    const { operation, filePath, description, contentPreview, oldContent, newContent, changeContext } = context;
+    logger.consoleLog(`\n🔐 File Operation Preview: ${operation.toUpperCase()}`);
+    logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+    logger.consoleLog(`📁 File: ${filePath}`);
+    logger.consoleLog(`📝 Action: ${description}`);
+    // Show risk assessment
+    const riskAssessment = analyzeOperationRisk(context);
+    const riskColor = riskAssessment.level === 'LOW' ? '🟢' : riskAssessment.level === 'MEDIUM' ? '🟡' : '🔴';
+    logger.consoleLog(`${riskColor} Risk Level: ${riskAssessment.level} - ${riskAssessment.reason}`);
+    if (operation === 'edit' && oldContent && newContent) {
+        // Show diff preview for edit operations
+        logger.consoleLog(`\n📊 Change Summary:`);
+        if (changeContext) {
+            logger.consoleLog(`   • Lines added: ${changeContext.linesAdded}`);
+            logger.consoleLog(`   • Lines removed: ${changeContext.linesRemoved}`);
+            logger.consoleLog(`   • Total lines after change: ${changeContext.totalLines}`);
+            logger.consoleLog(`   • Affected line numbers: ${changeContext.affectedLineNumbers.join(', ')}`);
+        }
+        logger.consoleLog(`\n📄 Diff Preview (showing changes):`);
+        logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+        showDiffPreview(oldContent, newContent);
+    }
+    else if (operation === 'write') {
+        // Show content preview for write operations
+        const contentLength = newContent?.length || contentPreview?.length || 0;
+        logger.consoleLog(`\n📊 Content Summary:`);
+        logger.consoleLog(`   • Content length: ${contentLength} characters`);
+        if (newContent || contentPreview) {
+            const content = newContent || contentPreview || '';
+            const lines = content.split('\n');
+            logger.consoleLog(`   • Total lines: ${lines.length}`);
+            // Detect content type
+            const contentType = detectContentType(filePath, content);
+            logger.consoleLog(`   • Detected type: ${contentType}`);
+            logger.consoleLog(`\n📄 Content Preview (first/last 10 lines):`);
+            logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+            showContentPreview(content);
+        }
+    }
+    logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+}
+/**
+ * Show a side-by-side or unified diff preview
+ */
+function showDiffPreview(oldContent, newContent) {
+    const oldLines = oldContent.split('\n');
+    const newLines = newContent.split('\n');
+    // Simple line-by-line diff (could be enhanced with proper diff algorithm)
+    const maxLines = Math.max(oldLines.length, newLines.length);
+    const contextLines = 3; // Show 3 lines of context around changes
+    let changes = [];
+    // Detect changes (simplified diff)
+    for (let i = 0; i < maxLines; i++) {
+        const oldLine = i < oldLines.length ? oldLines[i] : undefined;
+        const newLine = i < newLines.length ? newLines[i] : undefined;
+        if (oldLine === newLine) {
+            changes.push({ lineNum: i + 1, type: 'unchanged', oldLine, newLine });
+        }
+        else if (oldLine === undefined) {
+            changes.push({ lineNum: i + 1, type: 'added', newLine });
+        }
+        else if (newLine === undefined) {
+            changes.push({ lineNum: i + 1, type: 'removed', oldLine });
+        }
+        else {
+            changes.push({ lineNum: i + 1, type: 'removed', oldLine });
+            changes.push({ lineNum: i + 1, type: 'added', newLine });
+        }
+    }
+    // Show relevant changes with context
+    const changedLineNums = changes
+        .filter(c => c.type !== 'unchanged')
+        .map(c => c.lineNum);
+    if (changedLineNums.length === 0) {
+        logger.consoleLog(`   (No line changes detected)`);
+        return;
+    }
+    // Show up to 20 lines of diff to avoid overwhelming output
+    const diffLines = changes.slice(0, 20);
+    for (const change of diffLines) {
+        const lineNumStr = change.lineNum.toString().padStart(4, ' ');
+        switch (change.type) {
+            case 'unchanged':
+                if (change.oldLine !== undefined) {
+                    logger.consoleLog(`  ${lineNumStr}   ${change.oldLine}`);
+                }
+                break;
+            case 'removed':
+                logger.consoleLog(`- ${lineNumStr}   ${change.oldLine || ''}`);
+                break;
+            case 'added':
+                logger.consoleLog(`+ ${lineNumStr}   ${change.newLine || ''}`);
+                break;
+        }
+    }
+    if (changes.length > 20) {
+        logger.consoleLog(`   ... (${changes.length - 20} more lines)`);
+    }
+}
+/**
+ * Show preview of file content
+ */
+function showContentPreview(content) {
+    const lines = content.split('\n');
+    const maxPreviewLines = 20;
+    if (lines.length <= maxPreviewLines) {
+        // Show all lines if content is short
+        lines.forEach((line, i) => {
+            const lineNum = (i + 1).toString().padStart(4, ' ');
+            logger.consoleLog(`  ${lineNum}   ${line}`);
+        });
+    }
+    else {
+        // Show first 10 and last 10 lines
+        const firstLines = lines.slice(0, 10);
+        const lastLines = lines.slice(-10);
+        firstLines.forEach((line, i) => {
+            const lineNum = (i + 1).toString().padStart(4, ' ');
+            logger.consoleLog(`  ${lineNum}   ${line}`);
+        });
+        logger.consoleLog(`   ...   (${lines.length - 20} lines omitted)`);
+        lastLines.forEach((line, i) => {
+            const lineNum = (lines.length - 10 + i + 1).toString().padStart(4, ' ');
+            logger.consoleLog(`  ${lineNum}   ${line}`);
+        });
+    }
+}
+/**
+ * Analyze the risk level of a file operation
+ */
+function analyzeOperationRisk(context) {
+    const { operation, filePath, newContent, contentPreview } = context;
+    const content = newContent || contentPreview || '';
+    // Check for high-risk patterns
+    const highRiskPatterns = [
+        /package\.json.*"scripts"/s,
+        /\.env/i,
+        /docker/i,
+        /\.sh$/,
+        /\.bat$/,
+        /\.cmd$/,
+        /sudo|rm\s+-rf|chmod\s+777/,
+        /eval\s*\(|exec\s*\(/,
+        /process\.env\s*\[/
+    ];
+    // Check for medium-risk patterns
+    const mediumRiskPatterns = [
+        /config/i,
+        /\.json$/,
+        /import.*from.*http/,
+        /require.*http/,
+        /fetch\s*\(/,
+        /\.key$|\.pem$|\.crt$/i
+    ];
+    // Check file path risks
+    if (filePath.includes('node_modules')) {
+        return { level: 'HIGH', reason: 'Modifying node_modules can break dependencies' };
+    }
+    if (filePath.includes('.git/')) {
+        return { level: 'HIGH', reason: 'Modifying .git directory can corrupt repository' };
+    }
+    // Check content risks
+    for (const pattern of highRiskPatterns) {
+        if (pattern.test(content) || pattern.test(filePath)) {
+            return { level: 'HIGH', reason: 'Contains potentially dangerous operations or sensitive files' };
+        }
+    }
+    for (const pattern of mediumRiskPatterns) {
+        if (pattern.test(content) || pattern.test(filePath)) {
+            return { level: 'MEDIUM', reason: 'Contains configuration or network operations' };
+        }
+    }
+    // Default to low risk for typical development files
+    if (operation === 'edit') {
+        return { level: 'LOW', reason: 'Targeted edit operation to existing file' };
+    }
+    else {
+        return { level: 'LOW', reason: 'Standard file write operation' };
+    }
+}
+/**
+ * Detect the type of content being written
+ */
+function detectContentType(filePath, content) {
+    const extension = filePath.split('.').pop()?.toLowerCase();
+    // File extension based detection
+    const extensionTypes = {
+        'js': 'JavaScript',
+        'ts': 'TypeScript',
+        'jsx': 'React JSX',
+        'tsx': 'React TSX',
+        'json': 'JSON Configuration',
+        'html': 'HTML Document',
+        'css': 'CSS Stylesheet',
+        'scss': 'SCSS Stylesheet',
+        'md': 'Markdown Document',
+        'txt': 'Text File',
+        'yml': 'YAML Configuration',
+        'yaml': 'YAML Configuration',
+        'xml': 'XML Document',
+        'py': 'Python Script',
+        'sh': 'Shell Script',
+        'bat': 'Batch Script'
+    };
+    if (extension && extensionTypes[extension]) {
+        return extensionTypes[extension];
+    }
+    // Content-based detection
+    if (content.includes('export') || content.includes('import')) {
+        return 'JavaScript/TypeScript Module';
+    }
+    if (content.includes('<html') || content.includes('<!DOCTYPE')) {
+        return 'HTML Document';
+    }
+    if (content.includes('{') && content.includes('}')) {
+        try {
+            JSON.parse(content);
+            return 'JSON Data';
+        }
+        catch {
+            // Not valid JSON
+        }
     }
+    return 'Text Content';
 }
 /**
  * Show detailed information about the file operation
  */
 async function showFileOperationDetails(context) {
     const { operation, filePath, description, contentPreview } = context;
-    console.log(`\n📋 Detailed File Operation Information:`);
-    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-    console.log(`🔧 Operation Type: ${operation.toUpperCase()}`);
-    console.log(`📁 Target File: ${filePath}`);
-    console.log(`📝 Description: ${description}`);
-    console.log(`📂 Working Directory: ${process.cwd()}`);
+    logger.consoleLog(`\n📋 Detailed File Operation Information:`);
+    logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+    logger.consoleLog(`🔧 Operation Type: ${operation.toUpperCase()}`);
+    logger.consoleLog(`📁 Target File: ${filePath}`);
+    logger.consoleLog(`📝 Description: ${description}`);
+    logger.consoleLog(`📂 Working Directory: ${process.cwd()}`);
     // Show file status
     try {
         const fs = await import('fs/promises');
         const stats = await fs.stat(filePath);
-        console.log(`📊 File exists: YES`);
-        console.log(`📅 Last modified: ${stats.mtime.toLocaleString()}`);
-        console.log(`📏 File size: ${stats.size} bytes`);
+        logger.consoleLog(`📊 File exists: YES`);
+        logger.consoleLog(`📅 Last modified: ${stats.mtime.toLocaleString()}`);
+        logger.consoleLog(`📏 File size: ${stats.size} bytes`);
     }
     catch (error) {
-        console.log(`📊 File exists: NO (will be created)`);
+        logger.consoleLog(`📊 File exists: NO (will be created)`);
     }
     // Show full content if available
     if (contentPreview) {
-        console.log(`\n📄 Full Content Preview:`);
-        console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-        console.log(contentPreview);
-        console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+        logger.consoleLog(`\n📄 Full Content Preview:`);
+        logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+        logger.consoleLog(contentPreview);
+        logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
     }
     // Show security information
-    console.log(`\n🔒 Security Information:`);
-    console.log(`• File path is validated and restricted to working directory`);
-    console.log(`• Operation will be performed atomically with backup`);
-    console.log(`• You can undo changes using git if needed`);
-    console.log(`\n💡 Recommendation:`);
+    logger.consoleLog(`\n🔒 Security Information:`);
+    logger.consoleLog(`• File path is validated and restricted to working directory`);
+    logger.consoleLog(`• Operation will be performed atomically with backup`);
+    logger.consoleLog(`• You can undo changes using git if needed`);
+    logger.consoleLog(`\n💡 Recommendation:`);
     if (operation === 'write' && contentPreview) {
-        console.log(`• WRITE operation will ${contentPreview.includes('export') ? 'create a new file' : 'replace file content'}`);
-        console.log(`• Consider approving if the content looks correct`);
+        logger.consoleLog(`• WRITE operation will ${contentPreview.includes('export') ? 'create a new file' : 'replace file content'}`);
+        logger.consoleLog(`• Consider approving if the content looks correct`);
     }
     else if (operation === 'edit') {
-        console.log(`• EDIT operation will make targeted changes to existing file`);
-        console.log(`• Generally safer than write operations`);
+        logger.consoleLog(`• EDIT operation will make targeted changes to existing file`);
+        logger.consoleLog(`• Generally safer than write operations`);
     }
     await inquirer.prompt([{ type: 'input', name: 'continue', message: 'Press Enter to continue...' }]);
 }
@@ -151,13 +361,13 @@ export function clearSessionApprovals() {
  */
 export function showApprovalStatus() {
     const status = getSessionApprovalStatus();
-    console.log('\n📊 Current File Operation Approval Status:');
-    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-    console.log(`🚀 Dangerous Mode (auto-approve all): ${status.dangerousMode ? '✅ ENABLED' : '❌ Disabled'}`);
-    console.log(`✏️  Edit operations for session: ${status.editApproved ? '✅ Auto-approved' : '❌ Require approval'}`);
-    console.log(`📝 Write operations for session: ${status.writeApproved ? '✅ Auto-approved' : '❌ Require approval'}`);
+    logger.consoleLog('\n📊 Current File Operation Approval Status:');
+    logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+    logger.consoleLog(`🚀 Dangerous Mode (auto-approve all): ${status.dangerousMode ? '✅ ENABLED' : '❌ Disabled'}`);
+    logger.consoleLog(`✏️  Edit operations for session: ${status.editApproved ? '✅ Auto-approved' : '❌ Require approval'}`);
+    logger.consoleLog(`📝 Write operations for session: ${status.writeApproved ? '✅ Auto-approved' : '❌ Require approval'}`);
     if (status.dangerousMode) {
-        console.log(`\n⚠️  WARNING: Dangerous mode is enabled - all file operations will be auto-approved!`);
+        logger.consoleLog(`\n⚠️  WARNING: Dangerous mode is enabled - all file operations will be auto-approved!`);
     }
-    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+    logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 }

package/dist/utils/interrupt-handler.js

@@ -0,0 +1,127 @@
+import { logger } from './logger.js';
+export class UserInterruptError extends Error {
+    constructor(message = 'User paused operation') {
+        super(message);
+        this.isUserInterrupt = true;
+        this.name = 'UserInterruptError';
+    }
+}
+export class InterruptHandler {
+    constructor() {
+        this.isListening = false;
+        this.interrupted = false;
+        this.readline = null;
+    }
+    /**
+     * Start listening for 'q' key to interrupt
+     */
+    startListening() {
+        if (this.isListening)
+            return;
+        this.isListening = true;
+        this.interrupted = false;
+        // Set stdin to raw mode to capture single key presses
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.setEncoding('utf8');
+            const onKeyPress = (key) => {
+                if (key === 'q' || key === 'Q') {
+                    this.interrupted = true;
+                    logger.debug('🛑 User pressed Q - interrupt signal received', { component: 'InterruptHandler' });
+                    this.stopListening();
+                    // Just show a simple newline - no dramatic messages
+                    process.stdout.write('\n');
+                }
+                // Handle Ctrl+C gracefully
+                if (key === '\u0003') { // Ctrl+C
+                    logger.debug('🛑 User pressed Ctrl+C - graceful exit', { component: 'InterruptHandler' });
+                    process.stdout.write('\n\n👋 Goodbye!\n');
+                    process.exit(0);
+                }
+            };
+            process.stdin.on('data', onKeyPress);
+            // Store the listener for cleanup
+            this._keyPressListener = onKeyPress;
+        }
+    }
+    /**
+     * Stop listening for interrupts
+     */
+    stopListening() {
+        if (!this.isListening)
+            return;
+        this.isListening = false;
+        if (process.stdin.isTTY) {
+            // Remove the specific listener
+            if (this._keyPressListener) {
+                process.stdin.removeListener('data', this._keyPressListener);
+                this._keyPressListener = null;
+            }
+            // Reset stdin to normal mode
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+        }
+    }
+    /**
+     * Check if user has interrupted
+     */
+    isInterrupted() {
+        return this.interrupted;
+    }
+    /**
+     * Reset interrupt state
+     */
+    reset() {
+        this.interrupted = false;
+    }
+    /**
+     * Throw interrupt error if interrupted
+     */
+    throwIfInterrupted() {
+        if (this.interrupted) {
+            logger.debug('User requested pause', { component: 'InterruptHandler' });
+            throw new UserInterruptError();
+        }
+    }
+}
+// Global interrupt handler instance
+export const interruptHandler = new InterruptHandler();
+/**
+ * Convenience function to check for interrupt during async operations
+ */
+export function checkInterrupt() {
+    interruptHandler.throwIfInterrupted();
+}
+/**
+ * Wrapper for async operations that can be interrupted
+ */
+export async function interruptible(operation, checkInterval = 100) {
+    return new Promise((resolve, reject) => {
+        let completed = false;
+        // Start the operation
+        operation()
+            .then(result => {
+            completed = true;
+            resolve(result);
+        })
+            .catch(error => {
+            completed = true;
+            reject(error);
+        });
+        // Check for interrupts periodically
+        const checkInterrupts = () => {
+            if (completed)
+                return;
+            try {
+                checkInterrupt();
+                setTimeout(checkInterrupts, checkInterval);
+            }
+            catch (error) {
+                completed = true;
+                reject(error);
+            }
+        };
+        setTimeout(checkInterrupts, checkInterval);
+    });
+}