@hivetechs/hive-ai
Version:
Real-time streaming AI consensus platform with HTTP+SSE MCP integration for Claude Code, VS Code, Cursor, and Windsurf - powered by OpenRouter's unified API
682 lines • 30.4 kB
JavaScript
/**
* Expert CLI Commands - Advanced features for power users
*
* Provides expert-level commands for pipeline debugging, performance analysis,
* monitoring, and system optimization.
*/
import { structuredLogger } from './structured-logger.js';
import { globalPerformanceMonitor } from './performance-monitor.js';
import { globalAdvancedAlerting } from './advanced-alerting.js';
import { globalPipelineTracer } from './pipeline-tracer.js';
export class ExpertCLICommands {
/**
* PIPELINE DEBUGGING AND ANALYSIS
*/
/**
* Deep pipeline analysis for a conversation
*/
async debugConversation(conversationId, options = {}) {
try {
structuredLogger.info('Starting conversation debug analysis', { conversationId, options });
const analysis = {
conversationId,
timestamp: new Date().toISOString(),
stages: {},
performance: {},
quality: {},
traces: []
};
// Get conversation data from database
const { getDatabase, getConversationHistory } = await import('../storage/unified-database.js');
const db = await getDatabase();
const conversation = await db.get('SELECT * FROM conversations WHERE id = ?', [conversationId]);
if (!conversation) {
return {
success: false,
error: `Conversation ${conversationId} not found`
};
}
// Get conversation messages
const messages = await getConversationHistory(conversationId, 100);
analysis.messageCount = messages.length;
// Extract stage results
const stageMessages = messages.filter(msg => msg.content.includes('_FULL_ANSWER:') && msg.role === 'assistant');
stageMessages.forEach(msg => {
const stageMatch = msg.content.match(/(\w+)_FULL_ANSWER:\s*(.+)/s);
if (stageMatch) {
const stageName = stageMatch[1].toLowerCase();
const stageContent = stageMatch[2].trim();
analysis.stages[stageName] = {
timestamp: msg.timestamp,
contentLength: stageContent.length,
wordCount: stageContent.split(/\s+/).length,
content: options.verbose ? stageContent : stageContent.substring(0, 200) + '...'
};
}
});
// Get performance metrics if requested
if (options.includeMetrics) {
try {
const perfMetrics = await db.all('SELECT * FROM performance_metrics WHERE conversation_id = ? ORDER BY timestamp DESC', [conversationId]);
analysis.performance = perfMetrics.length > 0 ? JSON.parse(perfMetrics[0].metrics_data || '{}') : {};
}
catch (error) {
analysis.performance = { error: 'Could not retrieve performance metrics' };
}
}
// Get trace data if requested
if (options.includeTraces) {
const traces = globalPipelineTracer.getTraces({ conversationId });
analysis.traces = traces.map(trace => ({
id: trace.id,
operationType: trace.operationType,
totalDuration: trace.totalDuration,
spanCount: trace.spans.length,
efficiency: trace.performance.efficiency,
bottlenecks: trace.performance.bottlenecks.length,
recommendations: trace.performance.recommendations
}));
}
// Generate insights
analysis.insights = this.generateConversationInsights(analysis);
return {
success: true,
data: analysis,
message: `Conversation debug analysis completed for ${conversationId}`
};
}
catch (error) {
structuredLogger.error('Conversation debug failed', { conversationId }, error);
return {
success: false,
error: error.message
};
}
}
/**
* Profile pipeline performance
*/
async profilePipeline(profileName, options = {}) {
try {
structuredLogger.info('Starting pipeline profiling', { profileName, options });
if (options.realTime) {
return this.startRealTimeProfiler();
}
const timeframe = options.duration || '1h';
const report = await globalPerformanceMonitor.generatePerformanceReport(timeframe);
const profileData = {
timeframe,
summary: report.summary,
trends: report.trends,
bottlenecks: report.bottlenecks,
recommendations: report.recommendations,
timestamp: new Date().toISOString()
};
// Add comparison if requested
if (options.includeComparison && timeframe !== '1h') {
const baselineReport = await globalPerformanceMonitor.generatePerformanceReport('1h');
profileData.comparison = {
baseline: baselineReport.summary,
current: report.summary,
improvement: this.calculatePerformanceImprovement(baselineReport.summary, report.summary)
};
}
return {
success: true,
data: profileData,
message: `Pipeline profiling completed for ${timeframe}`
};
}
catch (error) {
structuredLogger.error('Pipeline profiling failed', { profileName, options }, error);
return {
success: false,
error: error.message
};
}
}
/**
* Analyze performance bottlenecks
*/
async analyzeBottlenecks(timeframe = '1h') {
try {
structuredLogger.info('Analyzing performance bottlenecks', { timeframe });
const bottlenecks = await globalPerformanceMonitor.identifyBottlenecks(timeframe);
const tracingStats = globalPipelineTracer.getTracingStats();
const analysis = {
timeframe,
totalBottlenecks: bottlenecks.length,
criticalBottlenecks: bottlenecks.filter(b => b.impact === 'critical').length,
highImpactBottlenecks: bottlenecks.filter(b => b.impact === 'high').length,
bottlenecks: bottlenecks.map(b => ({
component: b.component,
issue: b.issue,
impact: b.impact,
frequency: b.frequency,
avgDelay: `${Math.round(b.avgDelayMs)}ms`,
recommendation: b.recommendation
})),
componentBreakdown: tracingStats.componentBreakdown,
frequentBottlenecks: Object.entries(tracingStats.bottleneckFrequency)
.sort(([, a], [, b]) => b - a)
.slice(0, 5)
.map(([name, count]) => ({ name, occurrences: count })),
recommendations: this.generateBottleneckRecommendations(bottlenecks)
};
return {
success: true,
data: analysis,
message: `Bottleneck analysis completed for ${timeframe}`
};
}
catch (error) {
structuredLogger.error('Bottleneck analysis failed', { timeframe }, error);
return {
success: false,
error: error.message
};
}
}
/**
* MONITORING AND ALERTING
*/
/**
* Configure advanced alerts
*/
async configureAlerts(action, params) {
try {
structuredLogger.info('Configuring alerts', { action, params });
switch (action) {
case 'list':
const rules = globalAdvancedAlerting.getRules();
const stats = globalAdvancedAlerting.getAlertingStats();
return {
success: true,
data: {
rules: rules.map(rule => ({
id: rule.id,
name: rule.name,
enabled: rule.enabled,
category: rule.category,
severity: rule.severity,
triggeredCount: rule.triggeredCount,
lastTriggered: rule.lastTriggered
})),
stats
},
message: `Found ${rules.length} alert rules`
};
case 'add':
if (!params || !params.name || !params.condition) {
return { success: false, error: 'Missing required parameters: name, condition' };
}
const ruleId = globalAdvancedAlerting.addRule(params);
return {
success: true,
data: { ruleId },
message: `Alert rule '${params.name}' created with ID: ${ruleId}`
};
case 'update':
if (!params || !params.id) {
return { success: false, error: 'Missing required parameter: id' };
}
const updated = globalAdvancedAlerting.updateRule(params.id, params);
return {
success: updated,
message: updated ? `Alert rule ${params.id} updated` : `Alert rule ${params.id} not found`
};
case 'remove':
if (!params || !params.id) {
return { success: false, error: 'Missing required parameter: id' };
}
const removed = globalAdvancedAlerting.removeRule(params.id);
return {
success: removed,
message: removed ? `Alert rule ${params.id} removed` : `Alert rule ${params.id} not found`
};
case 'test':
// Trigger a test alert
const testRuleId = globalAdvancedAlerting.addRule({
name: 'Test Alert',
description: 'Test alert for verification',
enabled: true,
category: 'performance',
severity: 'low',
condition: {
type: 'threshold',
metric: 'test.value',
operator: '>',
value: 0
},
actions: [
{ type: 'log', config: { level: 'info' }, enabled: true }
],
throttle: { enabled: false, windowMinutes: 1, maxAlerts: 1 }
});
// Clean up test rule
setTimeout(() => {
globalAdvancedAlerting.removeRule(testRuleId);
}, 5000);
return {
success: true,
data: { testRuleId },
message: 'Test alert rule created and will be automatically removed in 5 seconds'
};
default:
return { success: false, error: `Unknown action: ${action}` };
}
}
catch (error) {
structuredLogger.error('Alert configuration failed', { action, params }, error);
return {
success: false,
error: error.message
};
}
}
/**
* Monitor system health and alerts
*/
async monitorDashboard(options = {}) {
try {
structuredLogger.info('Generating monitoring dashboard', { options });
if (options.live) {
return this.startLiveMonitoring(options.duration || 60);
}
// Get comprehensive system status
const { globalHealthMonitor } = await import('./health-monitor.js');
const systemHealth = globalHealthMonitor.getSystemHealth();
const alertStats = globalAdvancedAlerting.getAlertingStats();
const performanceStats = globalPipelineTracer.getTracingStats();
const recentAlerts = globalAdvancedAlerting.getAlerts({
resolved: false,
since: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString()
});
const dashboard = {
timestamp: new Date().toISOString(),
systemHealth: {
overall: systemHealth.overall,
components: {
openrouter: {
status: systemHealth.openrouter.status,
latency: systemHealth.openrouter.averageLatency || 0,
uptime: systemHealth.openrouter.uptime || 99.5
},
database: {
status: systemHealth.database.status,
connections: systemHealth.database.activeConnections || 1
}
}
},
alerts: {
total: alertStats.totalAlerts,
unresolved: alertStats.unresolvedAlerts,
last24h: alertStats.alertsLast24h,
bySeverity: alertStats.alertsBySeverity,
recentAlerts: recentAlerts.slice(0, 5).map(alert => ({
id: alert.id,
severity: alert.severity,
message: alert.message,
timestamp: alert.timestamp
}))
},
performance: {
activeTraces: performanceStats.activeTraces,
averageDuration: Math.round(performanceStats.averageDuration),
averageEfficiency: Math.round(performanceStats.averageEfficiency * 100) / 100,
componentBreakdown: performanceStats.componentBreakdown
},
recommendations: this.generateDashboardRecommendations(systemHealth, alertStats, performanceStats)
};
return {
success: true,
data: dashboard,
message: 'Monitoring dashboard generated successfully'
};
}
catch (error) {
structuredLogger.error('Dashboard monitoring failed', { options }, error);
return {
success: false,
error: error.message
};
}
}
/**
* PERFORMANCE ANALYSIS
*/
/**
* Compare performance across time periods
*/
async comparePerformance(baseline, current, focus) {
try {
structuredLogger.info('Comparing performance across periods', { baseline, current, focus });
const comparison = await globalPerformanceMonitor.comparePerformance(baseline, current);
const analysis = {
baseline: {
period: baseline,
summary: comparison.baseline.summary,
trends: comparison.baseline.trends
},
current: {
period: current,
summary: comparison.current.summary,
trends: comparison.current.trends
},
changes: {
performance: {
value: comparison.comparison.performanceChange,
trend: comparison.comparison.performanceChange > 0 ? 'slower' : 'faster',
significant: Math.abs(comparison.comparison.performanceChange) > 10
},
cost: {
value: comparison.comparison.costChange,
trend: comparison.comparison.costChange > 0 ? 'more expensive' : 'more efficient',
significant: Math.abs(comparison.comparison.costChange) > 15
},
quality: {
value: comparison.comparison.qualityChange,
trend: comparison.comparison.qualityChange > 0 ? 'improved' : 'declined',
significant: Math.abs(comparison.comparison.qualityChange) > 5
}
},
summary: comparison.comparison.summary,
recommendations: this.generateComparisonRecommendations(comparison)
};
// Filter by focus if specified
if (focus) {
analysis.focusArea = focus;
analysis.focusInsights = this.generateFocusInsights(focus, comparison);
}
return {
success: true,
data: analysis,
message: `Performance comparison completed: ${baseline} vs ${current}`
};
}
catch (error) {
structuredLogger.error('Performance comparison failed', { baseline, current, focus }, error);
return {
success: false,
error: error.message
};
}
}
/**
* Get optimization recommendations
*/
async getOptimizationRecommendations(focus) {
try {
structuredLogger.info('Generating optimization recommendations', { focus });
const recommendations = await globalPerformanceMonitor.getOptimizationRecommendations(focus);
const bottlenecks = await globalPerformanceMonitor.identifyBottlenecks('24h');
const analysis = {
focus: focus || 'all',
timestamp: new Date().toISOString(),
immediate: recommendations.filter(r => r.priority === 'high').map(r => ({
category: r.category,
description: r.description,
expectedImprovement: r.expectedImprovement,
effort: r.estimatedEffort
})),
planned: recommendations.filter(r => r.priority === 'medium').map(r => ({
category: r.category,
description: r.description,
expectedImprovement: r.expectedImprovement,
effort: r.estimatedEffort
})),
future: recommendations.filter(r => r.priority === 'low').map(r => ({
category: r.category,
description: r.description,
expectedImprovement: r.expectedImprovement,
effort: r.estimatedEffort
})),
criticalBottlenecks: bottlenecks.filter(b => b.impact === 'critical').map(b => ({
component: b.component,
issue: b.issue,
avgDelay: b.avgDelayMs,
recommendation: b.recommendation
})),
implementationPlan: this.generateImplementationPlan(recommendations, bottlenecks)
};
return {
success: true,
data: analysis,
message: `Generated ${recommendations.length} optimization recommendations`
};
}
catch (error) {
structuredLogger.error('Optimization recommendations failed', { focus }, error);
return {
success: false,
error: error.message
};
}
}
/**
* EXPORT AND REPORTING
*/
/**
* Export metrics for external monitoring tools
*/
async exportMetrics(format = 'json', options = {}) {
try {
structuredLogger.info('Exporting metrics', { format, options });
const exports = {};
// Export performance metrics
exports.performance = await globalPerformanceMonitor.exportMetrics(format);
// Export tracing data
if (!options.components || options.components.includes('tracing')) {
exports.tracing = globalPipelineTracer.exportTraces(format === 'prometheus' ? 'json' : format);
}
// Export alerting data
if (!options.components || options.components.includes('alerts')) {
const alerts = globalAdvancedAlerting.getAlerts();
exports.alerts = format === 'json' ? JSON.stringify(alerts, null, 2) : this.formatAlertsAsCSV(alerts);
}
// Combine exports based on format
let exportData;
switch (format) {
case 'json':
exportData = JSON.stringify(exports, null, 2);
break;
case 'csv':
exportData = Object.entries(exports).map(([key, data]) => `# ${key}\n${data}`).join('\n\n');
break;
case 'prometheus':
exportData = exports.performance; // Prometheus format only supports performance metrics
break;
default:
throw new Error(`Unsupported format: ${format}`);
}
const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
const filename = `hive-ai-metrics-${timestamp}.${format}`;
return {
success: true,
data: {
content: exportData,
filename,
size: exportData.length,
format
},
message: `Metrics exported in ${format} format (${exportData.length} bytes)`
};
}
catch (error) {
structuredLogger.error('Metrics export failed', { format, options }, error);
return {
success: false,
error: error.message
};
}
}
/**
* Helper methods
*/
generateConversationInsights(analysis) {
const insights = [];
if (analysis.stages.generator && analysis.stages.curator) {
const improvement = analysis.stages.curator.contentLength - analysis.stages.generator.contentLength;
const improvementPercent = Math.round((improvement / analysis.stages.generator.contentLength) * 100);
if (improvementPercent > 20) {
insights.push(`Consensus added significant value: ${improvementPercent}% more content in final answer`);
}
else if (improvementPercent < -10) {
insights.push(`Consensus refined the answer: ${Math.abs(improvementPercent)}% more concise final answer`);
}
}
const stageCount = Object.keys(analysis.stages).length;
if (stageCount < 4) {
insights.push(`Incomplete pipeline: Only ${stageCount} stages completed`);
}
if (analysis.performance && analysis.performance.pipeline) {
const totalTime = analysis.performance.pipeline.totalDuration;
if (totalTime > 30000) {
insights.push(`Slow execution: Total time ${Math.round(totalTime / 1000)}s exceeds recommended threshold`);
}
}
return insights;
}
calculatePerformanceImprovement(baseline, current) {
return {
responseTime: ((current.averageResponseTime - baseline.averageResponseTime) / baseline.averageResponseTime) * 100,
efficiency: ((current.overallEfficiency - baseline.overallEfficiency) / baseline.overallEfficiency) * 100,
costEfficiency: ((current.costEfficiency - baseline.costEfficiency) / baseline.costEfficiency) * 100
};
}
generateBottleneckRecommendations(bottlenecks) {
const recommendations = [];
const criticalBottlenecks = bottlenecks.filter(b => b.impact === 'critical');
if (criticalBottlenecks.length > 0) {
recommendations.push(`Address ${criticalBottlenecks.length} critical bottlenecks immediately`);
}
const componentCounts = bottlenecks.reduce((acc, b) => {
acc[b.component] = (acc[b.component] || 0) + 1;
return acc;
}, {});
const topComponent = Object.entries(componentCounts).sort(([, a], [, b]) => b - a)[0];
if (topComponent) {
recommendations.push(`Focus optimization efforts on ${topComponent[0]} component (${topComponent[1]} bottlenecks)`);
}
return recommendations;
}
generateDashboardRecommendations(systemHealth, alertStats, performanceStats) {
const recommendations = [];
if (systemHealth.overall !== 'healthy') {
recommendations.push('System health is degraded - investigate component issues');
}
if (alertStats.unresolvedAlerts > 5) {
recommendations.push(`High number of unresolved alerts (${alertStats.unresolvedAlerts}) - review and resolve critical issues`);
}
if (performanceStats.averageEfficiency < 50) {
recommendations.push('Low system efficiency detected - consider pipeline optimization');
}
if (performanceStats.activeTraces > 100) {
recommendations.push('High number of active traces - monitor for potential resource issues');
}
return recommendations;
}
generateComparisonRecommendations(comparison) {
const recommendations = [];
const changes = comparison.comparison;
if (changes.performanceChange > 20) {
recommendations.push('Significant performance degradation detected - investigate recent changes');
}
if (changes.costChange > 30) {
recommendations.push('Cost efficiency has declined significantly - review model selection and usage patterns');
}
if (Math.abs(changes.qualityChange) > 10) {
const direction = changes.qualityChange > 0 ? 'improved' : 'declined';
recommendations.push(`Quality has ${direction} significantly - analyze contributing factors`);
}
return recommendations;
}
generateFocusInsights(focus, comparison) {
const insights = [];
const changes = comparison.comparison;
switch (focus) {
case 'performance':
if (changes.performanceChange > 0) {
insights.push('Performance has degraded - consider optimizing slow operations');
}
else {
insights.push('Performance has improved - current optimizations are effective');
}
break;
case 'cost':
if (changes.costChange > 0) {
insights.push('Cost efficiency has improved - budget utilization is optimized');
}
else {
insights.push('Costs have increased - review model usage and pricing');
}
break;
case 'quality':
if (changes.qualityChange > 0) {
insights.push('Quality improvements detected - consensus pipeline is adding value');
}
else {
insights.push('Quality has declined - investigate pipeline configuration');
}
break;
}
return insights;
}
generateImplementationPlan(recommendations, bottlenecks) {
const plan = {
phase1: { title: 'Immediate Actions (0-1 week)', items: [] },
phase2: { title: 'Short-term Improvements (1-4 weeks)', items: [] },
phase3: { title: 'Long-term Optimization (1-3 months)', items: [] }
};
// Critical bottlenecks go to phase 1
bottlenecks.filter(b => b.impact === 'critical').forEach(b => {
plan.phase1.items.push(`Fix critical bottleneck: ${b.component} - ${b.recommendation}`);
});
// High priority recommendations go to phase 1
recommendations.filter(r => r.priority === 'high').forEach(r => {
plan.phase1.items.push(r.description);
});
// Medium priority goes to phase 2
recommendations.filter(r => r.priority === 'medium').forEach(r => {
plan.phase2.items.push(r.description);
});
// Low priority goes to phase 3
recommendations.filter(r => r.priority === 'low').forEach(r => {
plan.phase3.items.push(r.description);
});
return plan;
}
formatAlertsAsCSV(alerts) {
const headers = ['id', 'severity', 'message', 'timestamp', 'resolved', 'acknowledged'];
const rows = alerts.map(alert => [
alert.id,
alert.severity,
alert.message.replace(/,/g, ';'),
alert.timestamp,
alert.resolved.toString(),
alert.acknowledged.toString()
]);
return [headers.join(','), ...rows.map(row => row.join(','))].join('\n');
}
async startRealTimeProfiler() {
// Start real-time profiling (placeholder implementation)
return {
success: true,
message: 'Real-time profiler started - use Ctrl+C to stop',
data: { status: 'started', pid: process.pid }
};
}
async startLiveMonitoring(duration) {
// Start live monitoring (placeholder implementation)
return {
success: true,
message: `Live monitoring started for ${duration} seconds`,
data: { status: 'started', duration }
};
}
}
/**
* Global expert CLI commands instance
*/
export const expertCLI = new ExpertCLICommands();
//# sourceMappingURL=expert-cli-commands.js.map