elsabro 2.3.0 → 3.7.0

package/references/performance-profiler.md

@@ -0,0 +1,955 @@
+# ELSABRO Performance Profiler
+
+> Sistema de profiling para identificar y optimizar cuellos de botella en agentes y flows.
+
+## Arquitectura General
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                       Performance Profiler                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐         │
+│  │    Profiler     │  │BottleneckDetect │  │ MemoryAnalyzer  │         │
+│  │  ─────────────  │  │  ─────────────  │  │  ─────────────  │         │
+│  │ • Sampling      │  │ • Identify slow │  │ • Heap analysis │         │
+│  │ • Tracing       │  │ • Root cause    │  │ • Leaks detect  │         │
+│  │ • Benchmarking  │  │ • Suggestions   │  │ • GC pressure   │         │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘         │
+│                              │                                          │
+│  ┌───────────────────────────┴───────────────────────────────┐         │
+│  │                   LatencyTracker                           │         │
+│  │  • P50/P95/P99 • Histograms • SLO monitoring              │         │
+│  └────────────────────────────────────────────────────────────┘         │
+│                              │                                          │
+│  ┌───────────────────────────┴───────────────────────────────┐         │
+│  │                  PerformanceDashboard                      │         │
+│  │  • Real-time metrics • Flame graphs • Recommendations     │         │
+│  └────────────────────────────────────────────────────────────┘         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. Profiler
+
+### Propósito
+Recopila métricas de rendimiento mediante sampling y tracing.
+
+### Interfaz
+
+```typescript
+interface ProfilerOptions {
+  mode: 'sampling' | 'tracing' | 'both';
+  samplingInterval?: number;  // ms
+  traceAllCalls?: boolean;
+  captureStacks?: boolean;
+  maxSamples?: number;
+  targets?: ProfileTarget[];
+}
+
+interface ProfileTarget {
+  type: 'agent' | 'flow' | 'tool' | 'function';
+  name?: string;
+  pattern?: string;  // e.g., "elsabro-*"
+}
+
+interface ProfileSample {
+  timestamp: number;
+  target: string;
+  type: ProfileTarget['type'];
+  metrics: {
+    duration: number;
+    cpuTime?: number;
+    memoryDelta?: number;
+    tokenCount?: number;
+  };
+  stack?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+interface ProfileResult {
+  id: string;
+  startTime: number;
+  endTime: number;
+  duration: number;
+  samples: ProfileSample[];
+  summary: ProfileSummary;
+  hotspots: Hotspot[];
+  recommendations: Recommendation[];
+}
+
+interface ProfileSummary {
+  totalSamples: number;
+  byTarget: Map<string, TargetStats>;
+  byType: Map<string, TypeStats>;
+  percentiles: {
+    p50: number;
+    p75: number;
+    p90: number;
+    p95: number;
+    p99: number;
+  };
+}
+
+interface Hotspot {
+  target: string;
+  type: string;
+  totalTime: number;
+  percentage: number;
+  callCount: number;
+  avgDuration: number;
+  maxDuration: number;
+}
+
+interface Profiler {
+  // Lifecycle
+  start(options?: ProfilerOptions): Promise<void>;
+  stop(): Promise<ProfileResult>;
+  pause(): void;
+  resume(): void;
+  isRunning(): boolean;
+
+  // Manual instrumentation
+  startSpan(name: string, metadata?: Record<string, unknown>): ProfileSpan;
+  measure<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+
+  // Queries
+  getSamples(filter?: SampleFilter): ProfileSample[];
+  getStats(target?: string): TargetStats;
+  getCurrentProfile(): ProfileResult | null;
+
+  // Export
+  export(format: 'json' | 'flamegraph' | 'chrome-trace'): string;
+
+  // Events
+  onSample(callback: (sample: ProfileSample) => void): () => void;
+}
+
+interface ProfileSpan {
+  end(metadata?: Record<string, unknown>): void;
+  addEvent(name: string, data?: unknown): void;
+}
+```
+
+### Implementación
+
+```typescript
+class ProfilerImpl implements Profiler {
+  private options: ProfilerOptions;
+  private samples: ProfileSample[] = [];
+  private running: boolean = false;
+  private paused: boolean = false;
+  private startTime: number = 0;
+  private samplingTimer: NodeJS.Timer | null = null;
+  private sampleCallbacks: Set<(sample: ProfileSample) => void> = new Set();
+  private activeSpans: Map<string, { start: number; metadata: Record<string, unknown> }> = new Map();
+
+  constructor(private config: ProfilerConfig) {
+    this.options = {
+      mode: 'sampling',
+      samplingInterval: 100,
+      captureStacks: true,
+      maxSamples: 10000,
+      ...config.defaultOptions
+    };
+  }
+
+  async start(options?: ProfilerOptions): Promise<void> {
+    if (this.running) {
+      throw new Error('Profiler already running');
+    }
+
+    this.options = { ...this.options, ...options };
+    this.samples = [];
+    this.startTime = Date.now();
+    this.running = true;
+    this.paused = false;
+
+    if (this.options.mode === 'sampling' || this.options.mode === 'both') {
+      this.startSampling();
+    }
+
+    if (this.options.mode === 'tracing' || this.options.mode === 'both') {
+      this.setupTracing();
+    }
+  }
+
+  async stop(): Promise<ProfileResult> {
+    if (!this.running) {
+      throw new Error('Profiler not running');
+    }
+
+    this.running = false;
+
+    if (this.samplingTimer) {
+      clearInterval(this.samplingTimer);
+      this.samplingTimer = null;
+    }
+
+    const endTime = Date.now();
+    const duration = endTime - this.startTime;
+
+    const result: ProfileResult = {
+      id: `profile_${this.startTime}`,
+      startTime: this.startTime,
+      endTime,
+      duration,
+      samples: this.samples,
+      summary: this.calculateSummary(),
+      hotspots: this.identifyHotspots(),
+      recommendations: this.generateRecommendations()
+    };
+
+    return result;
+  }
+
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    this.paused = false;
+  }
+
+  isRunning(): boolean {
+    return this.running && !this.paused;
+  }
+
+  private startSampling(): void {
+    this.samplingTimer = setInterval(() => {
+      if (this.paused) return;
+      this.collectSample();
+    }, this.options.samplingInterval);
+  }
+
+  private collectSample(): void {
+    if (this.samples.length >= (this.options.maxSamples || 10000)) {
+      // Remove oldest samples
+      this.samples.shift();
+    }
+
+    // Collect system metrics
+    const memoryUsage = process.memoryUsage();
+
+    const sample: ProfileSample = {
+      timestamp: Date.now(),
+      target: 'system',
+      type: 'function',
+      metrics: {
+        duration: this.options.samplingInterval || 100,
+        memoryDelta: memoryUsage.heapUsed
+      }
+    };
+
+    if (this.options.captureStacks) {
+      sample.stack = this.captureStack();
+    }
+
+    this.samples.push(sample);
+    this.notifySample(sample);
+  }
+
+  private captureStack(): string[] {
+    const stack = new Error().stack || '';
+    return stack
+      .split('\n')
+      .slice(3) // Remove profiler frames
+      .map(line => line.trim())
+      .filter(line => !line.includes('node_modules'));
+  }
+
+  startSpan(name: string, metadata: Record<string, unknown> = {}): ProfileSpan {
+    const spanId = `${name}_${Date.now()}`;
+
+    this.activeSpans.set(spanId, {
+      start: Date.now(),
+      metadata
+    });
+
+    return {
+      end: (endMetadata?: Record<string, unknown>) => {
+        const spanData = this.activeSpans.get(spanId);
+        if (!spanData) return;
+
+        const duration = Date.now() - spanData.start;
+
+        const sample: ProfileSample = {
+          timestamp: spanData.start,
+          target: name,
+          type: this.inferType(name),
+          metrics: { duration },
+          metadata: { ...spanData.metadata, ...endMetadata }
+        };
+
+        this.samples.push(sample);
+        this.notifySample(sample);
+        this.activeSpans.delete(spanId);
+      },
+      addEvent: (eventName: string, data?: unknown) => {
+        // Add event to span metadata
+        const spanData = this.activeSpans.get(spanId);
+        if (spanData) {
+          spanData.metadata.events = spanData.metadata.events || [];
+          (spanData.metadata.events as unknown[]).push({
+            name: eventName,
+            timestamp: Date.now(),
+            data
+          });
+        }
+      }
+    };
+  }
+
+  async measure<T>(name: string, fn: () => T | Promise<T>): Promise<T> {
+    const span = this.startSpan(name);
+    try {
+      const result = await fn();
+      span.end({ success: true });
+      return result;
+    } catch (error) {
+      span.end({ success: false, error: String(error) });
+      throw error;
+    }
+  }
+
+  private inferType(name: string): ProfileTarget['type'] {
+    if (name.startsWith('agent:') || name.includes('Agent')) return 'agent';
+    if (name.startsWith('flow:') || name.includes('Flow')) return 'flow';
+    if (name.startsWith('tool:') || name.includes('Tool')) return 'tool';
+    return 'function';
+  }
+
+  private calculateSummary(): ProfileSummary {
+    const byTarget = new Map<string, TargetStats>();
+    const byType = new Map<string, TypeStats>();
+    const durations: number[] = [];
+
+    for (const sample of this.samples) {
+      durations.push(sample.metrics.duration);
+
+      // By target
+      if (!byTarget.has(sample.target)) {
+        byTarget.set(sample.target, {
+          count: 0,
+          totalDuration: 0,
+          minDuration: Infinity,
+          maxDuration: 0,
+          avgDuration: 0
+        });
+      }
+      const targetStats = byTarget.get(sample.target)!;
+      targetStats.count++;
+      targetStats.totalDuration += sample.metrics.duration;
+      targetStats.minDuration = Math.min(targetStats.minDuration, sample.metrics.duration);
+      targetStats.maxDuration = Math.max(targetStats.maxDuration, sample.metrics.duration);
+
+      // By type
+      if (!byType.has(sample.type)) {
+        byType.set(sample.type, {
+          count: 0,
+          totalDuration: 0,
+          percentage: 0
+        });
+      }
+      const typeStats = byType.get(sample.type)!;
+      typeStats.count++;
+      typeStats.totalDuration += sample.metrics.duration;
+    }
+
+    // Calculate averages
+    for (const stats of byTarget.values()) {
+      stats.avgDuration = stats.totalDuration / stats.count;
+    }
+
+    // Calculate percentiles
+    durations.sort((a, b) => a - b);
+    const percentiles = {
+      p50: this.percentile(durations, 50),
+      p75: this.percentile(durations, 75),
+      p90: this.percentile(durations, 90),
+      p95: this.percentile(durations, 95),
+      p99: this.percentile(durations, 99)
+    };
+
+    return {
+      totalSamples: this.samples.length,
+      byTarget,
+      byType,
+      percentiles
+    };
+  }
+
+  private percentile(sorted: number[], p: number): number {
+    if (sorted.length === 0) return 0;
+    const index = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, index)];
+  }
+
+  private identifyHotspots(): Hotspot[] {
+    const summary = this.calculateSummary();
+    const totalDuration = this.samples.reduce((sum, s) => sum + s.metrics.duration, 0);
+
+    const hotspots: Hotspot[] = [];
+
+    for (const [target, stats] of summary.byTarget) {
+      hotspots.push({
+        target,
+        type: this.samples.find(s => s.target === target)?.type || 'function',
+        totalTime: stats.totalDuration,
+        percentage: (stats.totalDuration / totalDuration) * 100,
+        callCount: stats.count,
+        avgDuration: stats.avgDuration,
+        maxDuration: stats.maxDuration
+      });
+    }
+
+    // Sort by total time descending
+    hotspots.sort((a, b) => b.totalTime - a.totalTime);
+    return hotspots.slice(0, 10);
+  }
+
+  private generateRecommendations(): Recommendation[] {
+    const recommendations: Recommendation[] = [];
+    const hotspots = this.identifyHotspots();
+    const summary = this.calculateSummary();
+
+    // Check for slow agents
+    for (const hotspot of hotspots) {
+      if (hotspot.type === 'agent' && hotspot.avgDuration > 30000) {
+        recommendations.push({
+          type: 'optimization',
+          severity: 'high',
+          target: hotspot.target,
+          message: `Agent "${hotspot.target}" has high average latency (${(hotspot.avgDuration / 1000).toFixed(1)}s)`,
+          suggestion: 'Consider using a faster model (haiku) or breaking into smaller tasks'
+        });
+      }
+    }
+
+    // Check for high variance
+    if (summary.percentiles.p99 > summary.percentiles.p50 * 10) {
+      recommendations.push({
+        type: 'investigation',
+        severity: 'medium',
+        target: 'system',
+        message: 'High latency variance detected (P99 >> P50)',
+        suggestion: 'Investigate outliers - may indicate resource contention or external delays'
+      });
+    }
+
+    // Check for memory issues
+    const memorySamples = this.samples.filter(s => s.metrics.memoryDelta);
+    if (memorySamples.length > 10) {
+      const memoryTrend = this.calculateTrend(memorySamples.map(s => s.metrics.memoryDelta!));
+      if (memoryTrend > 0.1) {
+        recommendations.push({
+          type: 'warning',
+          severity: 'high',
+          target: 'memory',
+          message: 'Potential memory leak detected - heap usage trending upward',
+          suggestion: 'Review object retention, consider manual cleanup between operations'
+        });
+      }
+    }
+
+    return recommendations;
+  }
+
+  private calculateTrend(values: number[]): number {
+    if (values.length < 2) return 0;
+    const first = values.slice(0, Math.floor(values.length / 2));
+    const second = values.slice(Math.floor(values.length / 2));
+    const avgFirst = first.reduce((a, b) => a + b, 0) / first.length;
+    const avgSecond = second.reduce((a, b) => a + b, 0) / second.length;
+    return (avgSecond - avgFirst) / avgFirst;
+  }
+
+  export(format: 'json' | 'flamegraph' | 'chrome-trace'): string {
+    switch (format) {
+      case 'json':
+        return JSON.stringify({
+          samples: this.samples,
+          summary: this.calculateSummary(),
+          hotspots: this.identifyHotspots()
+        }, null, 2);
+
+      case 'flamegraph':
+        return this.generateFlameGraphData();
+
+      case 'chrome-trace':
+        return this.generateChromeTrace();
+
+      default:
+        throw new Error(`Unknown format: ${format}`);
+    }
+  }
+
+  private generateFlameGraphData(): string {
+    // Generate folded stack format for flamegraph tools
+    const lines: string[] = [];
+
+    for (const sample of this.samples) {
+      if (sample.stack && sample.stack.length > 0) {
+        const stack = sample.stack.join(';');
+        lines.push(`${stack} ${sample.metrics.duration}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  private generateChromeTrace(): string {
+    // Generate Chrome DevTools trace format
+    const events: object[] = [];
+
+    for (const sample of this.samples) {
+      events.push({
+        name: sample.target,
+        cat: sample.type,
+        ph: 'X', // Complete event
+        ts: sample.timestamp * 1000, // microseconds
+        dur: sample.metrics.duration * 1000,
+        pid: 1,
+        tid: 1
+      });
+    }
+
+    return JSON.stringify({ traceEvents: events });
+  }
+
+  onSample(callback: (sample: ProfileSample) => void): () => void {
+    this.sampleCallbacks.add(callback);
+    return () => this.sampleCallbacks.delete(callback);
+  }
+
+  private notifySample(sample: ProfileSample): void {
+    this.sampleCallbacks.forEach(cb => cb(sample));
+  }
+
+  private setupTracing(): void {
+    // Hook into agent/flow/tool systems for automatic tracing
+    // This would integrate with the existing systems
+  }
+}
+
+interface TargetStats {
+  count: number;
+  totalDuration: number;
+  minDuration: number;
+  maxDuration: number;
+  avgDuration: number;
+}
+
+interface TypeStats {
+  count: number;
+  totalDuration: number;
+  percentage: number;
+}
+
+interface Recommendation {
+  type: 'optimization' | 'warning' | 'investigation';
+  severity: 'low' | 'medium' | 'high';
+  target: string;
+  message: string;
+  suggestion: string;
+}
+```
+
+---
+
+## 2. BottleneckDetector
+
+### Propósito
+Identifica automáticamente cuellos de botella y sus causas raíz.
+
+### Interfaz
+
+```typescript
+interface Bottleneck {
+  id: string;
+  type: 'latency' | 'throughput' | 'resource' | 'dependency';
+  location: string;
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  impact: {
+    latencyIncrease: number;  // percentage
+    throughputDecrease: number;
+    affectedOperations: string[];
+  };
+  rootCause?: RootCause;
+  detectedAt: string;
+}
+
+interface RootCause {
+  type: 'slow-model' | 'large-context' | 'serial-execution' | 'memory-pressure' | 'network' | 'external-api';
+  confidence: number;  // 0-1
+  evidence: string[];
+  relatedMetrics: Record<string, number>;
+}
+
+interface BottleneckDetector {
+  // Detection
+  analyze(profileResult: ProfileResult): Bottleneck[];
+  detectRealtime(samples: ProfileSample[]): Bottleneck[];
+
+  // Root cause analysis
+  findRootCause(bottleneck: Bottleneck): Promise<RootCause>;
+  correlate(bottlenecks: Bottleneck[]): CorrelationResult;
+
+  // Suggestions
+  suggest(bottleneck: Bottleneck): Suggestion[];
+  prioritize(bottlenecks: Bottleneck[]): Bottleneck[];
+}
+
+interface Suggestion {
+  action: string;
+  expectedImprovement: string;
+  effort: 'low' | 'medium' | 'high';
+  risk: 'low' | 'medium' | 'high';
+}
+```
+
+### Implementación
+
+```typescript
+class BottleneckDetectorImpl implements BottleneckDetector {
+  private thresholds: BottleneckThresholds;
+
+  constructor(config: BottleneckDetectorConfig) {
+    this.thresholds = {
+      latencyP95: 30000,  // 30s
+      latencyP99: 60000,  // 60s
+      throughputMin: 0.1, // ops/sec
+      memoryPressure: 0.8, // 80% heap
+      ...config.thresholds
+    };
+  }
+
+  analyze(profileResult: ProfileResult): Bottleneck[] {
+    const bottlenecks: Bottleneck[] = [];
+
+    // Analyze hotspots
+    for (const hotspot of profileResult.hotspots) {
+      if (hotspot.percentage > 30) {
+        bottlenecks.push(this.createBottleneck(
+          'latency',
+          hotspot.target,
+          hotspot.percentage > 50 ? 'high' : 'medium',
+          {
+            latencyIncrease: hotspot.percentage,
+            throughputDecrease: hotspot.percentage * 0.8,
+            affectedOperations: [hotspot.target]
+          }
+        ));
+      }
+    }
+
+    // Check percentiles
+    const { percentiles } = profileResult.summary;
+    if (percentiles.p95 > this.thresholds.latencyP95) {
+      bottlenecks.push(this.createBottleneck(
+        'latency',
+        'system',
+        percentiles.p99 > this.thresholds.latencyP99 ? 'critical' : 'high',
+        {
+          latencyIncrease: (percentiles.p95 / 10000) * 100,
+          throughputDecrease: 50,
+          affectedOperations: ['all']
+        }
+      ));
+    }
+
+    // Look for serial execution patterns
+    const serialPattern = this.detectSerialExecution(profileResult.samples);
+    if (serialPattern) {
+      bottlenecks.push(this.createBottleneck(
+        'throughput',
+        serialPattern.location,
+        'medium',
+        {
+          latencyIncrease: 0,
+          throughputDecrease: serialPattern.impact,
+          affectedOperations: serialPattern.operations
+        }
+      ));
+    }
+
+    return this.prioritize(bottlenecks);
+  }
+
+  async findRootCause(bottleneck: Bottleneck): Promise<RootCause> {
+    const evidence: string[] = [];
+    let type: RootCause['type'] = 'slow-model';
+    let confidence = 0.5;
+
+    // Analyze based on bottleneck type and location
+    if (bottleneck.location.includes('agent')) {
+      // Check if it's a model issue
+      if (bottleneck.location.includes('opus')) {
+        type = 'slow-model';
+        evidence.push('Using opus model which has higher latency');
+        confidence = 0.8;
+      }
+
+      // Check for large context
+      const contextMetric = bottleneck.impact.latencyIncrease;
+      if (contextMetric > 50) {
+        type = 'large-context';
+        evidence.push('High latency correlated with large input context');
+        confidence = 0.7;
+      }
+    }
+
+    if (bottleneck.type === 'throughput') {
+      type = 'serial-execution';
+      evidence.push('Operations executing sequentially instead of parallel');
+      confidence = 0.75;
+    }
+
+    if (bottleneck.type === 'resource') {
+      type = 'memory-pressure';
+      evidence.push('High memory usage detected during operation');
+      confidence = 0.7;
+    }
+
+    return {
+      type,
+      confidence,
+      evidence,
+      relatedMetrics: {
+        avgLatency: bottleneck.impact.latencyIncrease,
+        throughput: 100 - bottleneck.impact.throughputDecrease
+      }
+    };
+  }
+
+  suggest(bottleneck: Bottleneck): Suggestion[] {
+    const suggestions: Suggestion[] = [];
+
+    switch (bottleneck.rootCause?.type) {
+      case 'slow-model':
+        suggestions.push({
+          action: 'Switch to haiku model for exploration tasks',
+          expectedImprovement: '60-70% latency reduction',
+          effort: 'low',
+          risk: 'low'
+        });
+        suggestions.push({
+          action: 'Use model cascade (haiku → sonnet → opus)',
+          expectedImprovement: '40-50% cost and latency reduction',
+          effort: 'medium',
+          risk: 'low'
+        });
+        break;
+
+      case 'large-context':
+        suggestions.push({
+          action: 'Implement context windowing',
+          expectedImprovement: '30-40% latency reduction',
+          effort: 'medium',
+          risk: 'medium'
+        });
+        suggestions.push({
+          action: 'Use summarization for long conversations',
+          expectedImprovement: '20-30% token reduction',
+          effort: 'medium',
+          risk: 'low'
+        });
+        break;
+
+      case 'serial-execution':
+        suggestions.push({
+          action: 'Enable parallel execution for independent tasks',
+          expectedImprovement: 'Up to Nx speedup (N = parallel tasks)',
+          effort: 'low',
+          risk: 'low'
+        });
+        suggestions.push({
+          action: 'Use wave-based execution pattern',
+          expectedImprovement: '2-4x throughput improvement',
+          effort: 'medium',
+          risk: 'low'
+        });
+        break;
+
+      case 'memory-pressure':
+        suggestions.push({
+          action: 'Implement streaming for large outputs',
+          expectedImprovement: '50% memory reduction',
+          effort: 'medium',
+          risk: 'low'
+        });
+        suggestions.push({
+          action: 'Clear caches between operations',
+          expectedImprovement: '20-30% memory reduction',
+          effort: 'low',
+          risk: 'low'
+        });
+        break;
+    }
+
+    return suggestions;
+  }
+
+  prioritize(bottlenecks: Bottleneck[]): Bottleneck[] {
+    const severityScore: Record<string, number> = {
+      critical: 4,
+      high: 3,
+      medium: 2,
+      low: 1
+    };
+
+    return bottlenecks.sort((a, b) => {
+      // First by severity
+      const severityDiff = severityScore[b.severity] - severityScore[a.severity];
+      if (severityDiff !== 0) return severityDiff;
+
+      // Then by impact
+      return b.impact.latencyIncrease - a.impact.latencyIncrease;
+    });
+  }
+
+  private createBottleneck(
+    type: Bottleneck['type'],
+    location: string,
+    severity: Bottleneck['severity'],
+    impact: Bottleneck['impact']
+  ): Bottleneck {
+    return {
+      id: `bn_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+      type,
+      location,
+      severity,
+      impact,
+      detectedAt: new Date().toISOString()
+    };
+  }
+
+  private detectSerialExecution(samples: ProfileSample[]): {
+    location: string;
+    impact: number;
+    operations: string[];
+  } | null {
+    // Detect if operations that could be parallel are running serially
+    const agentSamples = samples.filter(s => s.type === 'agent');
+
+    // Group by time windows
+    const windows: ProfileSample[][] = [];
+    let currentWindow: ProfileSample[] = [];
+    let lastEnd = 0;
+
+    for (const sample of agentSamples) {
+      if (sample.timestamp > lastEnd + 1000) {
+        if (currentWindow.length > 0) {
+          windows.push(currentWindow);
+        }
+        currentWindow = [sample];
+      } else {
+        currentWindow.push(sample);
+      }
+      lastEnd = sample.timestamp + sample.metrics.duration;
+    }
+
+    // Check if any window has only 1 sample (serial) when it could have more
+    const serialWindows = windows.filter(w => w.length === 1);
+    if (serialWindows.length > windows.length * 0.7) {
+      return {
+        location: 'agent-execution',
+        impact: 50, // Estimated 50% throughput loss
+        operations: serialWindows.map(w => w[0].target)
+      };
+    }
+
+    return null;
+  }
+}
+```
+
+---
+
+## 3. Performance Dashboard
+
+### ASCII Dashboard
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                        ELSABRO Performance Dashboard                          ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║  Profile: flow_abc123  │  Duration: 5m 32s  │  Samples: 3,284                ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Latency Percentiles                              ║
+├──────────────────────────────────────────────────────────────────────────────┤
+║  P50:  2.3s   ████████░░░░░░░░░░░░                                           ║
+║  P75:  4.8s   ████████████████░░░░                                           ║
+║  P90:  8.2s   ██████████████████████████░░░░                                 ║
+║  P95: 12.5s   ████████████████████████████████████░░░░                       ║
+║  P99: 28.3s   ████████████████████████████████████████████████████████████   ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Top Hotspots                                     ║
+├──────────────────────────────────────────────────────────────────────────────┤
+║  1. agent:elsabro-executor     42.3%  ████████████████████████████░░░░       ║
+║  2. agent:elsabro-verifier     18.7%  ████████████░░░░░░░░░░░░░░░░░░░░       ║
+║  3. tool:Read                   8.2%  █████░░░░░░░░░░░░░░░░░░░░░░░░░░░       ║
+║  4. agent:Explore               6.5%  ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░       ║
+║  5. flow:parallel-join          4.1%  ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░       ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Bottlenecks Detected                             ║
+├──────────────────────────────────────────────────────────────────────────────┤
+║  🔴 HIGH: agent:elsabro-executor - Slow model latency                        ║
+║     └─ Suggestion: Use haiku for exploration, opus only for implementation   ║
+║                                                                               ║
+║  🟡 MEDIUM: flow:development - Serial execution detected                     ║
+║     └─ Suggestion: Enable parallel branches for independent tasks            ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Resource Usage                                   ║
+├──────────────────────────────────────────────────────────────────────────────┤
+║  Memory: ████████████████░░░░ 78% (312MB / 400MB)                            ║
+║  Tokens: ████████░░░░░░░░░░░░ 42% (84K / 200K budget)                        ║
+║  API:    ██████████████░░░░░░ 68% (34 / 50 req/min)                          ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Recommendations                                  ║
+├──────────────────────────────────────────────────────────────────────────────┤
+║  1. [HIGH] Switch exploration agents to haiku model                          ║
+║     Expected: 60-70% latency reduction | Effort: Low | Risk: Low             ║
+║                                                                               ║
+║  2. [MEDIUM] Enable parallel execution in development flow                   ║
+║     Expected: 2-4x throughput improvement | Effort: Low | Risk: Low          ║
+║                                                                               ║
+║  3. [LOW] Implement context summarization for long sessions                  ║
+║     Expected: 20-30% token reduction | Effort: Medium | Risk: Low            ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 4. Comandos CLI
+
+```bash
+# Iniciar profiling
+/elsabro:profile start
+
+# Detener y ver resultados
+/elsabro:profile stop
+
+# Ver dashboard en tiempo real
+/elsabro:profile dashboard
+
+# Exportar resultados
+/elsabro:profile export --format flamegraph --output profile.svg
+
+# Analizar bottlenecks
+/elsabro:profile bottlenecks
+
+# Ver recomendaciones
+/elsabro:profile recommendations
+
+# Benchmark específico
+/elsabro:profile benchmark agent:elsabro-executor --iterations 10
+```
+
+---
+
+## Referencias
+
+- **REF-013**: Observability System
+- **REF-020**: Cost Tracking
+- **REF-031**: Esta referencia (Performance Profiler)