👁️ François Observer

📊 Vue d'ensemble

L'Observer est composé de 5 agents spécialisés qui tournent en permanence en arrière-plan et surveillent différents aspects de François :

• Performance Observer — Métriques de performance (FPS, latence, throughput)
• Error Observer — Détection et catégorisation des erreurs
• Resource Observer — Usage CPU/RAM/GPU/Disk
• Health Observer — Score de santé composite (0-100)
• Timeline Observer — Timeline d'événements (100K buffer, 24h retention)

Tous les agents communiquent via un event bus et publient leurs observations dans des stores Zustand accessibles à l'UI.

🎯 Objectifs

• Détection proactive : Identifier les problèmes avant qu'ils n'impactent l'utilisateur
• Debugging facilité : Timeline détaillée de tous les événements pour reproduire les bugs
• Auto-correction : Recovery automatique pour certaines erreurs (reconnexion API, garbage collection...)
• Observabilité : Dashboard temps réel de la santé de François

🔍 Agent 1 : Performance Observer

Responsabilités

Surveille les performances temps réel de François : FPS de l'UI, latence des opérations, throughput du CPU/GPU.

Métriques collectées

• FPS UI : Frame rate de l'interface (target 60 FPS)
• Latence P50/P95/P99 : Distribution des latences pour chaque opération (search, parse, render...)
• Throughput : Tokens/s (Claude), Ops/s (GPU), MB/s (I/O)
• Frame drops : Nombre de frames <16.67ms (détecte les freezes UI)
• Memory pressure : Détection de fuites mémoire (heap growth anormal)
• Event loop lag : Mesure si l'event loop JavaScript est bloquée

Alertes

// Alerte si FPS < 30 pendant >2s
if (fps < 30 && duration > 2000) {
    observer.alert({
        level: "high",
        message: "UI freeze detected",
        context: { fps, duration }
    });
}

Visualisation

Dashboard temps réel dans l'UI avec graphes sparkline : FPS, latence P99, throughput GPU. Accessible via Cmd+Shift+P → "Show Performance Dashboard".

🚨 Agent 2 : Error Observer

Responsabilités

Intercepte toutes les erreurs (JavaScript, Rust, Claude API) et les catégorise intelligemment.

Catégorisation automatique

• Critical : Erreurs bloquantes (crash, API key invalide, device lost...)
• High : Erreurs impactantes (file operation failed, parse error, network timeout...)
• Medium : Erreurs récupérables (cache miss, retry succeeded...)
• Low : Warnings (deprecated API, slow operation...)

Stack traces enrichis

L'Observer enrichit les stack traces avec du contexte :

Error: Failed to parse file
  at gpu_parser.rs:245
  → Context:
    - File: src/components/Button.tsx
    - Size: 4.2 KB
    - Language: TypeScript
    - GPU Backend: Metal
    - Last modified: 2s ago
  → Recent events:
    - [T-3s] File opened
    - [T-2s] Content changed
    - [T-1s] Parse triggered
    - [T-0s] Parse failed

Deduplication

Groupe les erreurs similaires pour éviter de spammer les logs. Si la même erreur se répète 10x en 5s, affiche "Error x10" au lieu de 10 lignes.

Auto-recovery

// Exemple : reconnexion API automatique
if (error.type === "ApiConnectionLost") {
    observer.attempt_recovery(async () => {
        await reconnect_api();
        await retry_last_request();
    });
}

💻 Agent 3 : Resource Observer

Responsabilités

Surveille l'usage des ressources système : CPU, RAM, GPU, Disk I/O, Network I/O.

Métriques collectées

• CPU usage : % par core + total (via sysinfo crate Rust)
• RAM usage : Heap JS, Stack Rust, VRAM GPU, Swap
• GPU usage : Utilisation %, température, fan speed, power draw
• Disk I/O : Read/Write MB/s, IOPS, queue depth
• Network I/O : Upload/Download KB/s (pour Claude API)

Alertes sur dépassements

// Alerte si RAM > 90%
if (ram_usage > 0.9) {
    observer.alert({
        level: "critical",
        message: "High memory usage",
        action: "Trigger garbage collection"
    });
    // Déclenche GC forcé
    trigger_gc();
}

Throttling intelligent

Si le système est sous pression (CPU >90%, RAM >80%), l'Observer throttle automatiquement les opérations non-critiques :

• Pause l'indexation GPU en arrière-plan
• Réduit la fréquence du file watcher
• Désactive les animations UI non essentielles

❤️ Agent 4 : Health Observer

Responsabilités

Calcule un score de santé global (0-100) basé sur toutes les métriques des autres Observers.

Calcul du score

health_score = (
    0.3 * performance_score +  // 30% weight
    0.3 * error_score +         // 30% weight
    0.2 * resource_score +      // 20% weight
    0.2 * stability_score       // 20% weight
)

// Exemple de calcul
performance_score = fps >= 50 ? 100 : (fps / 50) * 100
error_score = 100 - (critical_errors * 20 + high_errors * 5)
resource_score = 100 - max(cpu_usage, ram_usage, gpu_usage)
stability_score = uptime_hours / 24 * 100  // bonus si pas de crash

Seuils d'alerte

• 90-100 : Excellent ✅ (vert)
• 70-89 : Bon ⚠️ (jaune)
• 50-69 : Dégradé ⚠️ (orange)
• <50 : Critique 🚨 (rouge) → Alerte utilisateur

Checks actifs

L'Observer effectue des checks actifs toutes les 30s :

• Claude API reachable ? (ping)
• GPU responsive ? (test kernel)
• File system writable ? (test write)
• Sufficient disk space ? (>1 GB free)

Degraded mode

Si health < 50, François entre en degraded mode :

• Désactive le GPU (fallback CPU)
• Désactive l'Autopilot
• Réduit l'usage réseau (batch requests)
• Affiche un banner "Degraded Mode" avec bouton "Attempt Recovery"

⏱️ Agent 5 : Timeline Observer

Responsabilités

Enregistre tous les événements dans une timeline circulaire de 100K événements max (FIFO). Rétention : 24h, puis archivage ou suppression.

Types d'événements capturés

• User actions : Clicks, keyboard, voice commands
• System events : File changes, network requests, API calls
• Performance events : Frame drops, slow operations (>100ms)
• Error events : Exceptions, warnings, crashes
• State changes : Autopilot state transitions, mode changes

Format d'événement

{
    "id": "evt_abc123",
    "timestamp": 1704067200000,
    "type": "user_action",
    "action": "click_button",
    "context": {
        "button_id": "run-tests",
        "screen": "editor",
        "file": "src/App.tsx"
    },
    "metadata": {
        "session_id": "sess_xyz",
        "user_id": "anon_hash",
        "version": "1.0.0"
    }
}

Buffer circulaire

// Implémentation Rust
struct TimelineBuffer {
    events: VecDeque,
    max_size: usize,  // 100_000
    retention: Duration,  // 24h
}

impl TimelineBuffer {
    fn push(&mut self, event: Event) {
        if self.events.len() >= self.max_size {
            self.events.pop_front();  // FIFO
        }
        self.events.push_back(event);
    }
}

Export & Replay

Exportez la timeline pour debugging :

# Export JSON
francois observer export timeline.json

# Export CSV
francois observer export timeline.csv --format=csv

# Export filtré
francois observer export errors.json --filter=error

# Replay (debug mode)
francois observer replay timeline.json

Filtrage avancé

Dans l'UI, filtrez la timeline par :

• Type (user_action, system_event, error...)
• Niveau (critical, high, medium, low)
• Agent (performance, error, resource, health, timeline)
• Texte (full-text search dans les events)
• Période (dernière heure, aujourd'hui, custom range)

📡 Event Bus

Tous les Observers communiquent via un event bus centralisé :

// Rust side (Tauri)
pub enum ObserverEvent {
    PerformanceMetric { fps: f32, latency_p99: f32 },
    ErrorDetected { level: ErrorLevel, message: String },
    ResourceUpdate { cpu: f32, ram: f32, gpu: f32 },
    HealthScoreChanged { score: u8, previous: u8 },
    TimelineEvent { event: Event },
}

// Publish
observer_bus.publish(ObserverEvent::PerformanceMetric {
    fps: 58.2,
    latency_p99: 23.4
});

// Subscribe (TypeScript side)
import { listen } from '@tauri-apps/api/event';

listen('observer-event', (event) => {
    // Update Zustand store
    useObserverStore.getState().updateMetrics(event.payload);
});

🎨 UI Dashboard

Accédez au dashboard Observer via Cmd+Shift+O ou menu "View → Observer Dashboard".

Sections du dashboard

• Health Score : Score 0-100 avec gauge circulaire
• Performance : Graphes FPS, latence P99, throughput
• Errors : Liste des erreurs récentes avec stack traces
• Resources : Graphes CPU, RAM, GPU, Disk I/O
• Timeline : Timeline scrollable avec filtres

⚙️ Configuration

Activer/Désactiver l'Observer

# Activer (activé par défaut)
francois config set OBSERVER_ENABLED=true

# Désactiver (pour debugging ou low-resource systems)
francois config set OBSERVER_ENABLED=false

Configurer les agents

# Activer/désactiver individuellement
francois config set OBSERVER_PERFORMANCE_ENABLED=true
francois config set OBSERVER_ERROR_ENABLED=true
francois config set OBSERVER_RESOURCE_ENABLED=true
francois config set OBSERVER_HEALTH_ENABLED=true
francois config set OBSERVER_TIMELINE_ENABLED=true

Configurer la timeline

# Taille du buffer (nombre d'événements)
francois config set OBSERVER_TIMELINE_SIZE=100000

# Rétention (durée)
francois config set OBSERVER_TIMELINE_RETENTION=24h

# Auto-export (pour debugging)
francois config set OBSERVER_AUTO_EXPORT=false

Configurer les alertes

# Seuil health score (en dessous = alerte)
francois config set OBSERVER_HEALTH_THRESHOLD=50

# Notifications desktop
francois config set OBSERVER_NOTIFICATIONS=true

# Niveau minimum pour notif (critical/high/medium/low)
francois config set OBSERVER_NOTIFICATION_LEVEL=high

🔬 Cas d'Usage

1. Debugging d'un crash

1. François crash → Timeline exportée automatiquement
2. Ouvrir le fichier exporté dans l'Observer Dashboard
3. Filtrer par niveau "critical" → voir l'erreur exacte
4. Remonter la timeline → voir les événements précédents
5. Replay la timeline pour reproduire le bug

2. Optimisation de performance

1. Observer Dashboard → Onglet Performance
2. Identifier les operations avec latence P99 élevée
3. Timeline → Filtrer par "slow_operation"
4. Analyser le contexte de ces opérations
5. Optimiser (activer GPU, augmenter cache, etc.)

3. Monitoring en production

1. Export timeline périodique (cron)
2. Agrégation des métriques (custom script)
3. Alertes sur health score < 70
4. Dashboards externes (Grafana, Datadog...)

🚀 Roadmap

• AI-powered anomaly detection : Utiliser Claude pour détecter des patterns anormaux dans la timeline
• Predictive health : Prédire les problèmes avant qu'ils n'arrivent (ML sur les métriques)
• Distributed tracing : Support OpenTelemetry pour intégration avec des systèmes externes
• Real-time collaboration : Observer partagé pour les équipes (voir les métriques des collègues)