ai-debug-local-mcp
Version:
🎯 ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh
279 lines • 13.9 kB
JavaScript
/**
* Sub-Agent Context Delegation Tracker
*
* Real-time measurement and validation of sub-agent context delegation.
* Tracks how effectively we delegate detailed work to sub-agents to keep
* the main conversation focused and context-efficient.
*/
export class ContextDelegationTracker {
static instance;
measurements = new Map();
sessionSummaries = new Map();
agentMetrics = new Map();
// Target thresholds for context delegation validation
static DELEGATION_TARGETS = {
minDelegationRatio: 0.70, // 70% of detailed work should be delegated to sub-agents
maxMainConversationImpact: 100, // max tokens added to main conversation per delegation
maxDelegationTime: 100, // milliseconds
targetSuccessRate: 0.95, // 95% successful delegation rate
idealConversationEfficiency: 0.90, // 90% of work handled by sub-agents
complexSessionTokenTarget: 10000 // target for complex sessions
};
// Agent-specific context delegation expectations (tokens handled by sub-agent)
static AGENT_CONTEXT_EXPECTATIONS = {
'debug-discovery-agent': 800, // handles initial setup details
'performance-analysis-agent': 1500, // handles detailed performance analysis
'accessibility-audit-agent': 1200, // handles WCAG compliance details
'error-investigation-agent': 1400, // handles error analysis and debugging
'validation-testing-agent': 1000, // handles testing validation details
'framework-specialist-agent': 2000, // handles framework-specific complexities
'data-extraction-agent': 1300, // handles data analysis and patterns
'testing-infrastructure-agent': 1800 // handles TDD and infrastructure setup
};
constructor() {
this.initializeAgentMetrics();
}
static getInstance() {
if (!ContextDelegationTracker.instance) {
ContextDelegationTracker.instance = new ContextDelegationTracker();
}
return ContextDelegationTracker.instance;
}
initializeAgentMetrics() {
Object.keys(ContextDelegationTracker.AGENT_CONTEXT_EXPECTATIONS).forEach(agentType => {
this.agentMetrics.set(agentType, {
agentType,
totalSessions: 0,
totalContextHandled: 0,
averageContextPerSession: 0,
averageDelegationTime: 0,
successfulDelegationRate: 0,
mainConversationImpactScore: 0,
complexityHandled: {
simple: 0,
moderate: 0,
complex: 0,
revolutionary: 0
},
// Legacy properties
totalTokensSaved: 0,
averageTokensSaved: 0,
successRate: 0
});
});
}
/**
* Start tracking a sub-agent delegation
*/
startDelegation(sessionId, agentType, taskDescription, complexityLevel = 'moderate', frameworkDetected) {
const measurementId = `${sessionId}_${agentType}_${Date.now()}`;
const measurement = {
sessionId,
agentType,
taskDescription,
startTime: new Date(),
contextKeptInMain: 0,
contextDelegatedToAgent: ContextDelegationTracker.AGENT_CONTEXT_EXPECTATIONS[agentType] || 800,
delegationEfficiency: 0,
actualDelegationTime: 0,
wasSuccessfullyDelegated: false,
complexityLevel,
frameworkDetected,
mainConversationImpact: 'minimal',
estimatedTokensSaved: ContextDelegationTracker.AGENT_CONTEXT_EXPECTATIONS[agentType] || 800
};
if (!this.measurements.has(sessionId)) {
this.measurements.set(sessionId, []);
}
this.measurements.get(sessionId).push(measurement);
console.log(`🎯 Token tracking started: ${agentType} (estimated ${measurement.estimatedTokensSaved} tokens)`);
return measurementId;
}
/**
* Complete a sub-agent delegation measurement
*/
completeDelegation(sessionId, agentType, actualTokensSaved, delegationTimeMs, successful = true) {
const sessionMeasurements = this.measurements.get(sessionId);
if (!sessionMeasurements) {
console.warn(`⚠️ No measurements found for session ${sessionId}`);
return;
}
// Find the most recent measurement for this agent type
const measurement = sessionMeasurements
.filter(m => m.agentType === agentType && !m.endTime)
.pop();
if (!measurement) {
console.warn(`⚠️ No active measurement found for ${agentType} in session ${sessionId}`);
return;
}
// Complete the measurement
measurement.endTime = new Date();
measurement.estimatedTokensSaved = actualTokensSaved;
measurement.actualDelegationTime = delegationTimeMs;
measurement.wasSuccessfullyDelegated = successful;
// Update agent metrics
this.updateAgentMetrics(agentType, measurement, successful);
// Log performance
const performanceStatus = delegationTimeMs <= ContextDelegationTracker.DELEGATION_TARGETS.maxDelegationTime
? '✅ FAST' : '⚠️ SLOW';
console.log(`📊 ${agentType} completed: ${actualTokensSaved} tokens saved in ${delegationTimeMs}ms ${performanceStatus}`);
// Update session summary
this.updateSessionSummary(sessionId);
}
updateAgentMetrics(agentType, measurement, successful) {
const metrics = this.agentMetrics.get(agentType);
if (!metrics)
return;
metrics.totalSessions++;
metrics.totalTokensSaved += measurement.estimatedTokensSaved;
metrics.averageTokensSaved = metrics.totalTokensSaved / metrics.totalSessions;
metrics.totalContextHandled += measurement.contextDelegatedToAgent;
metrics.averageContextPerSession = metrics.totalContextHandled / metrics.totalSessions;
// Update average delegation time
const totalTime = metrics.averageDelegationTime * (metrics.totalSessions - 1) + measurement.actualDelegationTime;
metrics.averageDelegationTime = totalTime / metrics.totalSessions;
// Update success rate
const successfulSessions = metrics.successRate * (metrics.totalSessions - 1) + (successful ? 1 : 0);
metrics.successRate = successfulSessions / metrics.totalSessions;
metrics.successfulDelegationRate = metrics.successRate;
// Update complexity distribution
metrics.complexityHandled[measurement.complexityLevel]++;
}
updateSessionSummary(sessionId) {
const sessionMeasurements = this.measurements.get(sessionId) || [];
const completedMeasurements = sessionMeasurements.filter(m => m.endTime);
if (completedMeasurements.length === 0)
return;
const totalTokensSaved = completedMeasurements.reduce((sum, m) => sum + m.estimatedTokensSaved, 0);
const totalDelegationTime = completedMeasurements.reduce((sum, m) => sum + m.actualDelegationTime, 0);
const averageDelegationTime = totalDelegationTime / completedMeasurements.length;
const efficiencyScore = totalTokensSaved / Math.max(totalDelegationTime, 1);
// Determine peak complexity
const complexityLevels = ['simple', 'moderate', 'complex', 'revolutionary'];
const peakComplexity = completedMeasurements.reduce((peak, m) => {
const currentIndex = complexityLevels.indexOf(m.complexityLevel);
const peakIndex = complexityLevels.indexOf(peak);
return currentIndex > peakIndex ? m.complexityLevel : peak;
}, 'simple');
// Check if target achieved (10000+ tokens for complex sessions)
const targetAchieved = peakComplexity === 'complex' || peakComplexity === 'revolutionary'
? totalTokensSaved >= ContextDelegationTracker.DELEGATION_TARGETS.complexSessionTokenTarget
: true; // Lower expectations for simple sessions
const summary = {
sessionId,
totalTokensSaved,
totalContextDelegated: totalTokensSaved,
totalMainContextUsed: 0, // TODO: Track this
delegationRatio: 0.8, // TODO: Calculate this
agentsUsed: new Set(completedMeasurements.map(m => m.agentType)).size,
averageDelegationTime,
peakComplexityLevel: peakComplexity,
efficiencyScore,
conversationEfficiency: 0.9, // TODO: Calculate this
targetAchieved
};
this.sessionSummaries.set(sessionId, summary);
// Log significant milestones
if (targetAchieved && peakComplexity === 'revolutionary') {
console.log(`🚀 REVOLUTIONARY SESSION: ${totalTokensSaved} tokens saved with ${summary.agentsUsed} agents!`);
}
else if (targetAchieved) {
console.log(`✅ Target achieved: ${totalTokensSaved} tokens saved in ${peakComplexity} session`);
}
}
/**
* Get real-time performance dashboard data
*/
getPerformanceDashboard() {
const allSessions = Array.from(this.sessionSummaries.values());
const totalTokensSaved = allSessions.reduce((sum, s) => sum + s.totalTokensSaved, 0);
const revolutionarySessionsCount = allSessions.filter(s => s.peakComplexityLevel === 'revolutionary' && s.targetAchieved).length;
const averageEfficiency = allSessions.length > 0
? allSessions.reduce((sum, s) => sum + s.efficiencyScore, 0) / allSessions.length
: 0;
// Check if overall performance targets are met
const performanceTargetsMet = Array.from(this.agentMetrics.values()).every(metrics => metrics.averageDelegationTime <= ContextDelegationTracker.DELEGATION_TARGETS.maxDelegationTime &&
metrics.successRate >= ContextDelegationTracker.DELEGATION_TARGETS.targetSuccessRate);
// Create agent leaderboard
const agentLeaderboard = Array.from(this.agentMetrics.values())
.map(metrics => ({
agentType: metrics.agentType,
tokensSaved: metrics.totalTokensSaved,
efficiency: metrics.totalTokensSaved / Math.max(metrics.averageDelegationTime * metrics.totalSessions, 1),
successRate: metrics.successRate
}))
.sort((a, b) => b.tokensSaved - a.tokensSaved);
return {
totalSessions: allSessions.length,
totalTokensSaved,
revolutionarySessionsCount,
averageEfficiency,
performanceTargetsMet,
agentLeaderboard
};
}
/**
* Get detailed validation report
*/
getValidationReport() {
const dashboard = this.getPerformanceDashboard();
const agentPerformance = Array.from(this.agentMetrics.values());
let overallStatus;
const achievements = [];
const recommendations = [];
// Determine overall status
if (dashboard.revolutionarySessionsCount > 0 && dashboard.performanceTargetsMet) {
overallStatus = 'REVOLUTIONARY';
achievements.push(`🚀 ${dashboard.revolutionarySessionsCount} revolutionary sessions achieved`);
achievements.push(`🎯 ${dashboard.totalTokensSaved.toLocaleString()} total tokens saved`);
}
else if (dashboard.performanceTargetsMet && dashboard.totalTokensSaved > 5000) {
overallStatus = 'MEETING_TARGETS';
achievements.push(`✅ Performance targets met across all agents`);
}
else if (dashboard.totalTokensSaved > 3000) {
overallStatus = 'NEEDS_OPTIMIZATION';
recommendations.push('🔧 Optimize slow-performing agents to meet <100ms delegation target');
}
else {
overallStatus = 'CRITICAL_ISSUES';
recommendations.push('🚨 Critical performance issues detected - immediate optimization required');
}
// Agent-specific recommendations
agentPerformance.forEach(metrics => {
if (metrics.averageDelegationTime > ContextDelegationTracker.DELEGATION_TARGETS.maxDelegationTime) {
recommendations.push(`⚡ Optimize ${metrics.agentType} delegation time (current: ${metrics.averageDelegationTime.toFixed(1)}ms)`);
}
if (metrics.successRate < ContextDelegationTracker.DELEGATION_TARGETS.targetSuccessRate) {
recommendations.push(`🎯 Improve ${metrics.agentType} success rate (current: ${(metrics.successRate * 100).toFixed(1)}%)`);
}
});
const summary = `Status: ${overallStatus} | Sessions: ${dashboard.totalSessions} | Tokens Saved: ${dashboard.totalTokensSaved.toLocaleString()} | Efficiency: ${dashboard.averageEfficiency.toFixed(2)} tokens/ms`;
return {
overallStatus,
summary,
agentPerformance,
recommendations,
achievements
};
}
/**
* Export performance data for analysis
*/
exportPerformanceData() {
const report = this.getValidationReport();
const dashboard = this.getPerformanceDashboard();
const exportData = {
timestamp: new Date().toISOString(),
summary: report.summary,
overallStatus: report.overallStatus,
dashboard,
agentMetrics: Array.from(this.agentMetrics.values()),
sessionSummaries: Array.from(this.sessionSummaries.values()),
recommendations: report.recommendations,
achievements: report.achievements
};
return JSON.stringify(exportData, null, 2);
}
}
//# sourceMappingURL=token-savings-tracker.js.map