hedgequantx 2.6.163 → 2.7.0

package/src/pages/algo/copy-trading.js

@@ -1,8 +1,6 @@
 /**
- * @fileoverview Professional Copy Trading Menu
+ * @fileoverview Copy Trading Mode
  * @module pages/algo/copy-trading
- * 
- * Copy trading configuration and session management
  */
 
 const chalk = require('chalk');
@@ -12,13 +10,7 @@ const readline = require('readline');
 const { connections } = require('../../services');
 const { AlgoUI, renderSessionSummary } = require('./ui');
 const { logger, prompts } = require('../../utils');
-const { checkMarketHours } = require('../../services/projectx/market');
-const { algoLogger } = require('./logger');
-const { CopyEngine } = require('./copy-engine');
-
-// AI Strategy Supervisor
-const aiService = require('../../services/ai');
-const StrategySupervisor = require('../../services/ai/strategy-supervisor');
+const { checkMarketHours } = require('../../services/rithmic/market');
 
 const log = logger.scope('CopyTrading');
 
@@ -28,233 +20,175 @@ const log = logger.scope('CopyTrading');
 const copyTradingMenu = async () => {
   log.info('Copy Trading menu opened');
 
+  // Check market hours
+  const market = checkMarketHours();
+  if (!market.isOpen && !market.message.includes('early')) {
+    console.log();
+    console.log(chalk.red(`  ${market.message}`));
+    console.log(chalk.gray('  Algo trading is only available when market is open'));
+    console.log();
+    await prompts.waitForEnter();
+    return;
+  }
+
   const allConns = connections.getAll();
 
-  if (allConns.length === 0) {
+  if (allConns.length < 2) {
     console.log();
-    console.log(chalk.yellow('  No connections found'));
-    console.log(chalk.gray('  Connect to a PropFirm first'));
+    console.log(chalk.yellow(`  Copy Trading requires 2 connected accounts (found: ${allConns.length})`));
+    console.log(chalk.gray('  Connect to another PropFirm first'));
     console.log();
     await prompts.waitForEnter();
     return;
   }
 
   console.log();
-  console.log(chalk.yellow.bold('  COPY TRADING - Professional Mode'));
+  console.log(chalk.yellow.bold('  Copy Trading Setup'));
   console.log();
 
   // Fetch all accounts
-  const spinner = ora({ text: 'FETCHING ACCOUNTS...', color: 'yellow' }).start();
+  const spinner = ora({ text: 'Fetching accounts...', color: 'yellow' }).start();
   const allAccounts = await fetchAllAccounts(allConns);
 
   if (allAccounts.length < 2) {
-    spinner.fail('NEED AT LEAST 2 ACTIVE ACCOUNTS');
-    console.log(chalk.gray('  Copy Trading requires a lead + at least one follower'));
+    spinner.fail('Need at least 2 active accounts');
     await prompts.waitForEnter();
     return;
   }
 
-  spinner.succeed(`Found ${allAccounts.length} accounts across ${allConns.length} connection(s)`);
+  spinner.succeed(`Found ${allAccounts.length} active accounts`);
 
   // Step 1: Select Lead Account
-  console.log();
-  console.log(chalk.cyan.bold('  Step 1: Select LEAD Account (source)'));
-  const leadIdx = await selectAccount('LEAD ACCOUNT:', allAccounts, []);
+  console.log(chalk.cyan('  Step 1: Select LEAD Account'));
+  const leadIdx = await selectAccount('Lead Account:', allAccounts, -1);
   if (leadIdx === null || leadIdx === -1) return;
   const lead = allAccounts[leadIdx];
 
-  // Step 2: Select Follower Accounts (multiple)
+  // Step 2: Select Follower Account
   console.log();
-  console.log(chalk.cyan.bold('  Step 2: Select FOLLOWER Account(s)'));
-  console.log(chalk.gray('  Select accounts to copy trades to'));
-  
-  const followers = [];
-  let selectingFollowers = true;
-  const excludeIndices = [leadIdx];
-  
-  while (selectingFollowers && excludeIndices.length < allAccounts.length) {
-    const followerIdx = await selectAccount(
-      followers.length === 0 ? 'FOLLOWER ACCOUNT:' : 'ADD ANOTHER FOLLOWER:',
-      allAccounts,
-      excludeIndices,
-      followers.length > 0
-    );
-    
-    if (followerIdx === null || followerIdx === -1) {
-      if (followers.length === 0) return;
-      selectingFollowers = false;
-    } else if (followerIdx === -2) {
-      selectingFollowers = false;
-    } else {
-      followers.push(allAccounts[followerIdx]);
-      excludeIndices.push(followerIdx);
-      console.log(chalk.green(`  Added: ${allAccounts[followerIdx].propfirm}`));
-    }
-  }
-
-  if (followers.length === 0) {
-    console.log(chalk.red('  No followers selected'));
-    await prompts.waitForEnter();
-    return;
-  }
+  console.log(chalk.cyan('  Step 2: Select FOLLOWER Account'));
+  const followerIdx = await selectAccount('Follower Account:', allAccounts, leadIdx);
+  if (followerIdx === null || followerIdx === -1) return;
+  const follower = allAccounts[followerIdx];
 
   // Step 3: Select Symbol
   console.log();
-  console.log(chalk.cyan.bold('  Step 3: Select Trading Symbol'));
+  console.log(chalk.cyan('  Step 3: Select Trading Symbol'));
   const symbol = await selectSymbol(lead.service);
   if (!symbol) return;
 
-  // Step 4: Configure contracts for each account
+  // Step 4: Configure Parameters
   console.log();
-  console.log(chalk.cyan.bold('  Step 4: Configure Contract Sizes'));
-  
-  const leadContracts = await prompts.numberInput(`${lead.propfirm} (LEAD) contracts:`, 1, 1, 10);
+  console.log(chalk.cyan('  Step 4: Configure Parameters'));
+
+  const leadContracts = await prompts.numberInput('Lead contracts:', 1, 1, 10);
   if (leadContracts === null) return;
-  lead.contracts = leadContracts;
-  
-  for (const follower of followers) {
-    const contracts = await prompts.numberInput(`${follower.propfirm} contracts:`, leadContracts, 1, 10);
-    if (contracts === null) return;
-    follower.contracts = contracts;
-  }
 
-  // Step 5: Risk parameters
-  console.log();
-  console.log(chalk.cyan.bold('  Step 5: Risk Parameters'));
-  
-  const dailyTarget = await prompts.numberInput('Daily target ($):', 1000, 1, 10000);
+  const followerContracts = await prompts.numberInput('Follower contracts:', leadContracts, 1, 10);
+  if (followerContracts === null) return;
+
+  const dailyTarget = await prompts.numberInput('Daily target ($):', 400, 1, 10000);
   if (dailyTarget === null) return;
 
-  const maxRisk = await prompts.numberInput('Max risk ($):', 500, 1, 5000);
+  const maxRisk = await prompts.numberInput('Max risk ($):', 200, 1, 5000);
   if (maxRisk === null) return;
 
-  // Step 6: Privacy
-  const showNames = await prompts.selectOption('ACCOUNT NAMES:', [
-    { label: 'HIDE ACCOUNT NAMES', value: false },
-    { label: 'SHOW ACCOUNT NAMES', value: true },
+  // Step 5: Privacy
+  const showNames = await prompts.selectOption('Account names:', [
+    { label: 'Hide account names', value: false },
+    { label: 'Show account names', value: true },
   ]);
   if (showNames === null) return;
 
-  // Step 7: AI Agents option
-  const aiAgents = aiService.getAgents();
-  let enableAI = false;
-  
-  if (aiAgents.length > 0) {
-    console.log();
-    console.log(chalk.magenta(`  ${aiAgents.length} AI AGENT(S) AVAILABLE:`));
-    aiAgents.forEach((agent, i) => {
-      const modelInfo = agent.model ? chalk.gray(` (${agent.model})`) : '';
-      console.log(chalk.white(`    ${i + 1}. ${agent.name}${modelInfo}`));
-    });
-    console.log();
-    
-    enableAI = await prompts.confirmPrompt('ACTIVATE AI MODELS?', true);
-    if (enableAI === null) return;
-    
-    if (enableAI) {
-      const mode = aiAgents.length >= 2 ? 'CONSENSUS' : 'INDIVIDUAL';
-      console.log(chalk.green(`  AI MODE: ${mode} (${aiAgents.length} agent${aiAgents.length > 1 ? 's' : ''})`));
-    } else {
-      console.log(chalk.gray('  AI AGENTS DISABLED FOR THIS SESSION'));
-    }
-  }
-
-  // Summary
+  // Confirm
   console.log();
-  console.log(chalk.white.bold('  ═══════════════════════════════════════'));
-  console.log(chalk.white.bold('  COPY TRADING CONFIGURATION'));
-  console.log(chalk.white.bold('  ═══════════════════════════════════════'));
+  console.log(chalk.white('  Summary:'));
   console.log(chalk.cyan(`  Symbol: ${symbol.name}`));
-  console.log(chalk.cyan(`  Lead: ${lead.propfirm} (${leadContracts} contracts)`));
-  console.log(chalk.cyan(`  Followers: ${followers.length}`));
-  followers.forEach(f => {
-    console.log(chalk.gray(`    → ${f.propfirm} (${f.contracts} contracts)`));
-  });
+  console.log(chalk.cyan(`  Lead: ${lead.propfirm} x${leadContracts}`));
+  console.log(chalk.cyan(`  Follower: ${follower.propfirm} x${followerContracts}`));
   console.log(chalk.cyan(`  Target: $${dailyTarget} | Risk: $${maxRisk}`));
-  console.log(chalk.white.bold('  ═══════════════════════════════════════'));
   console.log();
 
-  const confirm = await prompts.confirmPrompt('START COPY TRADING?', true);
+  const confirm = await prompts.confirmPrompt('Start Copy Trading?', true);
   if (!confirm) return;
 
   // Launch
   await launchCopyTrading({
     lead: { ...lead, symbol, contracts: leadContracts },
-    followers: followers.map(f => ({ ...f, symbol })),
+    follower: { ...follower, symbol, contracts: followerContracts },
     dailyTarget,
     maxRisk,
     showNames,
-    enableAI,
   });
 };
 
 /**
  * Fetch all active accounts from connections
+ * @param {Array} allConns - All connections
+ * @returns {Promise<Array>}
  */
 const fetchAllAccounts = async (allConns) => {
   const allAccounts = [];
 
-  const promises = allConns.map(async (conn) => {
+  for (const conn of allConns) {
     try {
       const result = await conn.service.getTradingAccounts();
       if (result.success && result.accounts) {
-        return result.accounts
-          .filter(a => a.status === 0)
-          .map(acc => ({
+        const active = result.accounts.filter(a => a.status === 0);
+        for (const acc of active) {
+          allAccounts.push({
             account: acc,
             service: conn.service,
             propfirm: conn.propfirm,
             type: conn.type,
-          }));
+          });
+        }
       }
     } catch (err) {
       log.warn('Failed to get accounts', { type: conn.type, error: err.message });
     }
-    return [];
-  });
-
-  const results = await Promise.all(promises);
-  results.forEach(accounts => allAccounts.push(...accounts));
+  }
 
   return allAccounts;
 };
 
 /**
  * Select account from list
+ * @param {string} message - Prompt message
+ * @param {Array} accounts - Available accounts
+ * @param {number} excludeIdx - Index to exclude
+ * @returns {Promise<number|null>}
  */
-const selectAccount = async (message, accounts, excludeIndices = [], allowDone = false) => {
+const selectAccount = async (message, accounts, excludeIdx) => {
   const options = accounts
     .map((a, i) => ({ a, i }))
-    .filter(x => !excludeIndices.includes(x.i))
+    .filter(x => x.i !== excludeIdx)
     .map(x => {
       const acc = x.a.account;
-      const balance = acc.balance !== null && acc.balance !== undefined
-        ? ` ($${acc.balance.toLocaleString()})`
-        : '';
-      const platform = x.a.type === 'rithmic' ? ' [Rithmic]' : '';
+      const balance = acc.balance !== null ? ` ($${acc.balance.toLocaleString()})` : '';
       return {
-        label: `${x.a.propfirm} - ${acc.accountName || acc.rithmicAccountId || acc.accountId}${balance}${platform}`,
+        label: `${x.a.propfirm} - ${acc.accountName || acc.rithmicAccountId || acc.name || acc.accountId}${balance}`,
         value: x.i,
       };
     });
 
-  if (allowDone) {
-    options.push({ label: chalk.green('✓ DONE ADDING FOLLOWERS'), value: -2 });
-  }
-  options.push({ label: chalk.gray('< CANCEL'), value: -1 });
-  
+  options.push({ label: '< Cancel', value: -1 });
   return prompts.selectOption(message, options);
 };
 
 /**
  * Select trading symbol
+ * @param {Object} service - Service instance
+ * @returns {Promise<Object|null>}
  */
 const selectSymbol = async (service) => {
-  const spinner = ora({ text: 'LOADING SYMBOLS...', color: 'yellow' }).start();
+  const spinner = ora({ text: 'Loading symbols...', color: 'yellow' }).start();
 
   try {
+    // Try Rithmic API first for consistency
     let contracts = await getContractsFromAPI();
 
+    // Fallback to service
     if (!contracts && typeof service.getContracts === 'function') {
       const result = await service.getContracts();
       if (result.success && result.contracts?.length > 0) {
@@ -263,34 +197,37 @@ const selectSymbol = async (service) => {
     }
 
     if (!contracts || !contracts.length) {
-      spinner.fail('NO CONTRACTS AVAILABLE');
+      spinner.fail('No contracts available');
       await prompts.waitForEnter();
       return null;
     }
 
     spinner.succeed(`Found ${contracts.length} contracts`);
 
-    // Sort by popular symbols first
-    const popular = ['ES', 'NQ', 'MES', 'MNQ', 'RTY', 'YM', 'CL', 'GC'];
-    contracts.sort((a, b) => {
-      const aIdx = popular.findIndex(p => (a.name || '').startsWith(p));
-      const bIdx = popular.findIndex(p => (b.name || '').startsWith(p));
-      if (aIdx !== -1 && bIdx !== -1) return aIdx - bIdx;
-      if (aIdx !== -1) return -1;
-      if (bIdx !== -1) return 1;
-      return (a.name || '').localeCompare(b.name || '');
-    });
+    // Build options from RAW API data - no static mapping
+    const options = [];
+    let currentGroup = null;
+
+    for (const c of contracts) {
+      // Use RAW API field: contractGroup
+      if (c.contractGroup && c.contractGroup !== currentGroup) {
+        currentGroup = c.contractGroup;
+        options.push({
+          label: chalk.cyan.bold(`── ${currentGroup} ──`),
+          value: null,
+          disabled: true,
+        });
+      }
 
-    const options = contracts.slice(0, 30).map(c => {
-      const name = c.name || c.symbol || c.baseSymbol;
-      const desc = c.description || '';
-      const label = desc ? `${name} - ${desc}` : name;
-      return { label, value: c };
-    });
+      // Use RAW API fields: name (symbol), description (full name), exchange
+      const label = `  ${c.name} - ${c.description} (${c.exchange})`;
+      options.push({ label, value: c });
+    }
 
-    options.push({ label: chalk.gray('< CANCEL'), value: null });
+    options.push({ label: '', value: null, disabled: true });
+    options.push({ label: chalk.gray('< Cancel'), value: null });
 
-    return prompts.selectOption('TRADING SYMBOL:', options);
+    return prompts.selectOption('Trading Symbol:', options);
   } catch (err) {
     spinner.fail(`Error loading contracts: ${err.message}`);
     await prompts.waitForEnter();
@@ -299,15 +236,17 @@ const selectSymbol = async (service) => {
 };
 
 /**
- * Get contracts from ProjectX API
+ * Get contracts from Rithmic API - RAW data only
+ * @returns {Promise<Array|null>}
  */
 const getContractsFromAPI = async () => {
   const allConns = connections.getAll();
-  const projectxConn = allConns.find(c => c.type === 'projectx');
+  const rithmicConn = allConns.find(c => c.type === 'rithmic');
 
-  if (projectxConn && typeof projectxConn.service.getContracts === 'function') {
-    const result = await projectxConn.service.getContracts();
+  if (rithmicConn && typeof rithmicConn.service.getContracts === 'function') {
+    const result = await rithmicConn.service.getContracts();
     if (result.success && result.contracts?.length > 0) {
+      // Return RAW API data - no mapping
       return result.contracts;
     }
   }
@@ -317,128 +256,159 @@ const getContractsFromAPI = async () => {
 
 /**
  * Launch Copy Trading session
+ * @param {Object} config - Session configuration
  */
 const launchCopyTrading = async (config) => {
-  const { lead, followers, dailyTarget, maxRisk, showNames, enableAI } = config;
+  const { lead, follower, dailyTarget, maxRisk, showNames } = config;
 
-  const leadName = showNames 
-    ? (lead.account.accountName || lead.account.accountId)
-    : 'Lead *****';
-  
-  const ui = new AlgoUI({ subtitle: 'COPY TRADING PRO', mode: 'copy-trading' });
+  // Account names (masked for privacy)
+  const leadName = showNames ? lead.account.accountId : 'HQX Lead *****';
+  const followerName = showNames ? follower.account.accountId : 'HQX Follower *****';
+
+  const ui = new AlgoUI({ subtitle: 'HQX Copy Trading', mode: 'copy-trading' });
 
   const stats = {
     leadName,
-    followerCount: followers.length,
+    followerName,
     leadSymbol: lead.symbol.name,
+    followerSymbol: follower.symbol.name,
     leadQty: lead.contracts,
+    followerQty: follower.contracts,
     target: dailyTarget,
     risk: maxRisk,
     pnl: 0,
-    sessionPnl: 0,
     trades: 0,
     wins: 0,
     losses: 0,
     latency: 0,
     connected: false,
-    platform: lead.type === 'rithmic' ? 'Rithmic' : 'ProjectX',
-    startTime: Date.now(),
-    aiSupervision: false,
-    aiMode: null,
-    agentCount: 0
+    platform: lead.account.platform || 'Rithmic',
   };
 
-  // Initialize AI Supervisor
-  if (enableAI) {
-    const aiAgents = aiService.getAgents();
-    stats.agentCount = aiAgents.length;
-    if (aiAgents.length > 0) {
-      const supervisorResult = StrategySupervisor.initialize(null, aiAgents, lead.service, lead.account.accountId);
-      stats.aiSupervision = supervisorResult.success;
-      stats.aiMode = supervisorResult.mode;
+  let running = true;
+  let stopReason = null;
+  
+  // Measure API latency (CLI <-> API)
+  const measureLatency = async () => {
+    try {
+      const start = Date.now();
+      await lead.service.getPositions(lead.account.accountId);
+      stats.latency = Date.now() - start;
+    } catch (e) {
+      stats.latency = 0;
     }
-  }
-
-  // Startup logs
-  const market = checkMarketHours();
-  const sessionName = market.session || 'AMERICAN';
-  const etTime = new Date().toLocaleTimeString('en-US', { 
-    hour: '2-digit', minute: '2-digit', timeZone: 'America/New_York' 
-  });
-
-  algoLogger.connectingToEngine(ui, lead.account.accountId);
-  algoLogger.engineStarting(ui, stats.platform, dailyTarget, maxRisk);
-  algoLogger.marketOpen(ui, sessionName.toUpperCase(), etTime);
-  algoLogger.info(ui, 'COPY MODE', `Lead: ${lead.propfirm} -> ${followers.length} follower(s)`);
-
-  if (stats.aiSupervision) {
-    const aiAgents = aiService.getAgents();
-    algoLogger.info(ui, 'AI SUPERVISION', `${aiAgents.length} agent(s) - LEARNING ACTIVE`);
-  }
+  };
 
-  // Create copy engine
-  const engine = new CopyEngine({
-    lead,
-    followers,
-    symbol: lead.symbol,
-    dailyTarget,
-    maxRisk,
-    ui,
-    stats
-  });
+  // Local copy trading - no external server needed
+  ui.addLog('info', `Starting copy trading on ${stats.platform}...`);
+  ui.addLog('info', `Lead: ${stats.leadName} -> Follower: ${stats.followerName}`);
+  ui.addLog('info', `Symbol: ${stats.symbol} | Target: $${dailyTarget} | Risk: $${maxRisk}`);
+  stats.connected = true;
+  
+  // Track lead positions and copy to follower
+  let lastLeadPositions = [];
+  
+  const pollAndCopy = async () => {
+    try {
+      // Get lead positions
+      const leadResult = await lead.service.getPositions(lead.account.accountId);
+      if (!leadResult.success) return;
+      
+      const currentPositions = leadResult.positions || [];
+      
+      // Detect new positions on lead
+      for (const pos of currentPositions) {
+        const existing = lastLeadPositions.find(p => p.contractId === pos.contractId);
+        if (!existing && pos.quantity !== 0) {
+          // New position opened - copy to follower
+          ui.addLog('trade', `Lead opened: ${pos.quantity > 0 ? 'LONG' : 'SHORT'} ${Math.abs(pos.quantity)}x ${pos.symbol || pos.contractId}`);
+          // TODO: Place order on follower account
+        }
+      }
+      
+      // Detect closed positions
+      for (const oldPos of lastLeadPositions) {
+        const stillOpen = currentPositions.find(p => p.contractId === oldPos.contractId);
+        if (!stillOpen || stillOpen.quantity === 0) {
+          ui.addLog('info', `Lead closed: ${oldPos.symbol || oldPos.contractId}`);
+          // TODO: Close position on follower account
+        }
+      }
+      
+      lastLeadPositions = currentPositions;
+      
+      // Update P&L from lead
+      const leadPnL = currentPositions.reduce((sum, p) => sum + (p.profitAndLoss || 0), 0);
+      if (leadPnL !== stats.pnl) {
+        const diff = leadPnL - stats.pnl;
+        if (Math.abs(diff) > 0.01 && stats.pnl !== 0) {
+          stats.trades++;
+          if (diff >= 0) stats.wins++;
+          else stats.losses++;
+        }
+        stats.pnl = leadPnL;
+      }
+      
+      // Check target/risk limits
+      if (stats.pnl >= dailyTarget) {
+        stopReason = 'target';
+        running = false;
+        ui.addLog('success', `TARGET REACHED! +$${stats.pnl.toFixed(2)}`);
+      } else if (stats.pnl <= -maxRisk) {
+        stopReason = 'risk';
+        running = false;
+        ui.addLog('error', `MAX RISK HIT! -$${Math.abs(stats.pnl).toFixed(2)}`);
+      }
+    } catch (e) {
+      // Silent fail - will retry
+    }
+  };
 
   // UI refresh loop
   const refreshInterval = setInterval(() => {
-    if (engine.running) ui.render(stats);
+    if (running) ui.render(stats);
   }, 250);
+  
+  // Measure API latency every 5 seconds
+  measureLatency(); // Initial measurement
+  const latencyInterval = setInterval(() => { if (running) measureLatency(); }, 5000);
+  
+  // Poll and copy every 2 seconds
+  pollAndCopy(); // Initial poll
+  const copyInterval = setInterval(() => { if (running) pollAndCopy(); }, 2000);
 
   // Keyboard handling
   const cleanupKeys = setupKeyboardHandler(() => {
-    engine.stop('manual');
+    running = false;
+    stopReason = 'manual';
   });
 
-  // Start engine
-  algoLogger.dataConnected(ui, 'API');
-  algoLogger.algoOperational(ui, stats.platform);
-  
-  const stopReason = await engine.start();
+  // Wait for stop
+  await new Promise((resolve) => {
+    const check = setInterval(() => {
+      if (!running) {
+        clearInterval(check);
+        resolve();
+      }
+    }, 100);
+  });
 
   // Cleanup
   clearInterval(refreshInterval);
+  clearInterval(latencyInterval);
+  clearInterval(copyInterval);
   if (cleanupKeys) cleanupKeys();
-
-  // Stop AI Supervisor
-  if (stats.aiSupervision) {
-    const aiSummary = StrategySupervisor.stop();
-    stats.aiLearning = {
-      optimizations: aiSummary.optimizationsApplied || 0,
-      patternsLearned: (aiSummary.winningPatterns || 0) + (aiSummary.losingPatterns || 0)
-    };
-  }
-
-  // Duration
-  const durationMs = Date.now() - stats.startTime;
-  const hours = Math.floor(durationMs / 3600000);
-  const minutes = Math.floor((durationMs % 3600000) / 60000);
-  const seconds = Math.floor((durationMs % 60000) / 1000);
-  stats.duration = hours > 0
-    ? `${hours}h ${minutes}m ${seconds}s`
-    : minutes > 0
-      ? `${minutes}m ${seconds}s`
-      : `${seconds}s`;
-
-  // Close log file
-  try { ui.closeLog(stats); } catch {}
-  
   ui.cleanup();
 
-  // Summary
+  // Show summary
   renderSessionSummary(stats, stopReason);
   await prompts.waitForEnter();
 };
 
 /**
  * Setup keyboard handler
+ * @param {Function} onStop - Stop callback
+ * @returns {Function|null} Cleanup function
  */
 const setupKeyboardHandler = (onStop) => {
   if (!process.stdin.isTTY) return null;