openvoiceui 1.0.0

package/src/core/Config.js

@@ -0,0 +1,173 @@
+/**
+ * Config — frontend config manager (ADR-009: simple manager pattern)
+ *
+ * Loads config from the server endpoint /api/config, merges with
+ * compile-time defaults, and exposes a simple get/set interface.
+ *
+ * Usage:
+ *   import { config } from './Config.js';
+ *
+ *   await config.load();             // fetch from server
+ *
+ *   config.get('tts.provider');      // → 'supertonic'
+ *   config.get('missing', 'default'); // → 'default'
+ *   config.set('ui.volume', 0.8);    // local override (not persisted)
+ *
+ *   config.onChange('tts.provider', (val) => { ... });
+ */
+
+import { eventBus } from './EventBus.js';
+
+/** Compile-time defaults — must not contain secrets */
+const DEFAULTS = {
+    tts: {
+        provider: 'groq',
+        volume: 1.0,
+        rate: 1.0,
+    },
+    stt: {
+        provider: 'webspeech',
+        language: 'en-US',
+        continuous: true,
+        interimResults: true,
+    },
+    ui: {
+        theme: 'dark',
+        wakeWord: true,
+        showTranscript: true,
+        showFace: true,
+    },
+    music: {
+        enabled: true,
+        duckVolume: 0.15,
+        duckDuration: 500,
+    },
+    session: {
+        key: 'voice-main',
+    },
+    api: {
+        baseUrl: '',  // same origin
+        configEndpoint: '/api/config',
+    },
+};
+
+class Config {
+    constructor() {
+        /** @type {Record<string, any>} flat key → value store */
+        this._store = {};
+        this._loaded = false;
+
+        // Seed with defaults
+        this._flattenInto(DEFAULTS, '');
+    }
+
+    /**
+     * Load config from the server, merging over defaults.
+     * Safe to call multiple times — subsequent calls re-fetch.
+     * @returns {Promise<void>}
+     */
+    async load() {
+        const endpoint = this.get('api.configEndpoint', '/api/config');
+        try {
+            const res = await fetch(endpoint);
+            if (res.ok) {
+                const data = await res.json();
+                this._flattenInto(data, '');
+                eventBus.emit('config:loaded', { source: 'server' });
+            } else {
+                console.warn(`[Config] Server returned ${res.status} — using defaults`);
+                eventBus.emit('config:loaded', { source: 'defaults' });
+            }
+        } catch (err) {
+            console.warn('[Config] Failed to fetch config — using defaults:', err.message);
+            eventBus.emit('config:loaded', { source: 'defaults' });
+        }
+        this._loaded = true;
+    }
+
+    /**
+     * Get a config value by dot-notation key.
+     * @param {string} key  e.g. 'tts.provider'
+     * @param {*} [fallback]
+     * @returns {*}
+     */
+    get(key, fallback = undefined) {
+        return key in this._store ? this._store[key] : fallback;
+    }
+
+    /**
+     * Set a config value locally (does not persist to server).
+     * Emits 'config:change' event.
+     * @param {string} key
+     * @param {*} value
+     */
+    set(key, value) {
+        const prev = this._store[key];
+        this._store[key] = value;
+        if (prev !== value) {
+            eventBus.emit('config:change', { key, value, prev });
+        }
+    }
+
+    /**
+     * Subscribe to changes for a specific key.
+     * @param {string} key
+     * @param {Function} handler  called with (newValue, oldValue)
+     * @returns {Function} unsubscribe
+     */
+    onChange(key, handler) {
+        return eventBus.on('config:change', ({ key: k, value, prev }) => {
+            if (k === key) handler(value, prev);
+        });
+    }
+
+    /**
+     * Return all config as a nested object (reconstructed from flat store).
+     * @returns {Record<string, any>}
+     */
+    all() {
+        const result = {};
+        for (const [key, value] of Object.entries(this._store)) {
+            this._setNested(result, key.split('.'), value);
+        }
+        return result;
+    }
+
+    /**
+     * Whether config has been loaded from server at least once.
+     * @returns {boolean}
+     */
+    get isLoaded() {
+        return this._loaded;
+    }
+
+    // ── private ──────────────────────────────────────────────────────────────
+
+    /** Recursively flatten an object into dot-notation keys in this._store */
+    _flattenInto(obj, prefix) {
+        for (const [k, v] of Object.entries(obj)) {
+            const fullKey = prefix ? `${prefix}.${k}` : k;
+            if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+                this._flattenInto(v, fullKey);
+            } else {
+                this._store[fullKey] = v;
+            }
+        }
+    }
+
+    /** Set a nested key path on an object */
+    _setNested(obj, parts, value) {
+        const key = parts[0];
+        if (parts.length === 1) {
+            obj[key] = value;
+        } else {
+            if (!obj[key] || typeof obj[key] !== 'object') obj[key] = {};
+            this._setNested(obj[key], parts.slice(1), value);
+        }
+    }
+}
+
+// Singleton
+export const config = new Config();
+
+export { Config };

package/src/core/EmotionEngine.js

@@ -0,0 +1,307 @@
+/**
+ * EmotionEngine — infers emotional state from LLM responses and drives face mood.
+ *
+ * Connects LLM response content to the FaceManager's mood system (P3-T8).
+ *
+ * Two signal sources (in priority order):
+ *   1. Explicit emotion_state from server (emitted as 'session:emotion' event)
+ *   2. Text-based keyword inference from LLM response text
+ *
+ * Usage:
+ *   import { emotionEngine } from './EmotionEngine.js';
+ *   emotionEngine.start();   // call once at app boot
+ *   emotionEngine.stop();    // call on teardown
+ *
+ * Events consumed from eventBus:
+ *   'session:message'   { role: 'assistant', text: string }  — infer mood from text
+ *   'session:emotion'   { mood, intensity, confidence }       — explicit override
+ *   'session:thinking'  {}                                    — face to 'thinking'
+ *   'tts:stop'          {}                                    — reset to neutral after speech
+ *
+ * Events emitted on eventBus:
+ *   'emotion:change'    { mood, intensity, source }           — mood was updated
+ *
+ * ADR-004: emotion_state schema — mood + intensity + confidence
+ * ADR-009: simple manager pattern (no framework)
+ */
+
+import { eventBus } from './EventBus.js';
+import { faceManager, VALID_MOODS } from '../face/BaseFace.js';
+
+// ── Keyword tables ─────────────────────────────────────────────────────────
+
+/**
+ * Mood inference rules.
+ * Each entry has a mood and an array of regex patterns.
+ * Rules are tested in order; first match wins.
+ * @type {Array<{mood: string, patterns: RegExp[]}>}
+ */
+const MOOD_RULES = [
+    {
+        mood: 'surprised',
+        patterns: [
+            /\bwh?oa+\b/i,
+            /\bwow\b/i,
+            /\bno way\b/i,
+            /\bholly?\s*sh+it\b/i,
+            /\bwhat the\b/i,
+            /\bseriously\?/i,
+            /\breally\?\b/i,
+            /\boh\s+sh+it\b/i,
+            /\bunbelievable\b/i,
+            /\bi can't believe\b/i
+        ]
+    },
+    {
+        mood: 'happy',
+        patterns: [
+            /\bha(ha)+\b/i,
+            /\blol\b/i,
+            /\blmao\b/i,
+            /\bexcellent\b/i,
+            /\bawesome\b/i,
+            /\bfantastic\b/i,
+            /\bperfect\b/i,
+            /\bcongrat(ulation)?s?\b/i,
+            /\bbrilliant\b/i,
+            /\blove it\b/i,
+            /\bthat's great\b/i,
+            /\bnice\b/i,
+            /\bsweet\b/i,
+            /\bwoo+\b/i,
+            /\blet'?s go\b/i
+        ]
+    },
+    {
+        mood: 'thinking',
+        patterns: [
+            /\bhmm+\b/i,
+            /\blet me think\b/i,
+            /\binteresting\b/i,
+            /\bcalculat/i,
+            /\banalyz/i,
+            /\bprocessing\b/i,
+            /\bconsidering\b/i,
+            /\bactually\b/i,
+            /\bwell,?\s+technically\b/i,
+            /\bto be (fair|honest)\b/i
+        ]
+    },
+    {
+        mood: 'sad',
+        patterns: [
+            /\bsorry\b/i,
+            /\bunfortunately\b/i,
+            /\bi (can't|cannot|couldn't)\b/i,
+            /\bfailed\b/i,
+            /\berror\b/i,
+            /\bmy bad\b/i,
+            /\bapolog/i,
+            /\bdisappoint/i,
+            /\bregret\b/i
+        ]
+    },
+    {
+        mood: 'angry',
+        patterns: [
+            /\bannoying\b/i,
+            /\bfrustrat/i,
+            /\bstupid\b/i,
+            /\bidiot/i,
+            /\bwhy would you\b/i,
+            /\bthat's wrong\b/i,
+            /\bfor f+uck'?s sake\b/i,
+            /\bfor (the love|crying out loud)\b/i
+        ]
+    }
+];
+
+// Minimum confidence to override neutral (0–1)
+const INFERENCE_THRESHOLD = 0.4;
+
+// ── EmotionEngine class ────────────────────────────────────────────────────
+
+class EmotionEngine {
+    constructor() {
+        /** @type {string} */
+        this._currentMood = 'neutral';
+        /** @type {number} */
+        this._currentIntensity = 0.5;
+        /** @type {boolean} */
+        this._active = false;
+        /** @type {Function[]} unsubscribe functions */
+        this._unsubs = [];
+        /** @type {ReturnType<typeof setTimeout>|null} */
+        this._resetTimer = null;
+    }
+
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+
+    /**
+     * Wire up EventBus subscriptions.  Call once at app boot.
+     */
+    start() {
+        if (this._active) return;
+        this._active = true;
+
+        this._unsubs = [
+            // Explicit server-provided emotion (highest priority)
+            eventBus.on('session:emotion', (data) => this._onExplicitEmotion(data)),
+
+            // Text-based inference on completed assistant message
+            eventBus.on('session:message', (data) => {
+                if (data?.role === 'assistant') {
+                    this._inferFromText(data.text);
+                }
+            }),
+
+            // When TTS finishes speaking, return to neutral after a short delay
+            eventBus.on('tts:stop', () => this._scheduleReset()),
+        ];
+
+        console.log('[EmotionEngine] Started');
+    }
+
+    /**
+     * Remove all EventBus subscriptions.
+     */
+    stop() {
+        if (!this._active) return;
+        this._active = false;
+
+        this._unsubs.forEach(unsub => unsub());
+        this._unsubs = [];
+
+        if (this._resetTimer) {
+            clearTimeout(this._resetTimer);
+            this._resetTimer = null;
+        }
+
+        console.log('[EmotionEngine] Stopped');
+    }
+
+    // ── Public API ───────────────────────────────────────────────────────────
+
+    /**
+     * Manually set a mood (useful for testing or external overrides).
+     * @param {string} mood  one of VALID_MOODS
+     * @param {number} [intensity=0.6]  0–1
+     */
+    setMood(mood, intensity = 0.6) {
+        this._applyMood(mood, intensity, 'manual');
+    }
+
+    /** @returns {string} current mood */
+    get currentMood() {
+        return this._currentMood;
+    }
+
+    /** @returns {number} current intensity (0–1) */
+    get currentIntensity() {
+        return this._currentIntensity;
+    }
+
+    // ── Private handlers ─────────────────────────────────────────────────────
+
+    /**
+     * Handle explicit emotion_state from server (ADR-004 schema).
+     * @param {{ mood?: string, intensity?: number, confidence?: number }} data
+     */
+    _onExplicitEmotion(data) {
+        if (!data?.mood) return;
+
+        const mood = VALID_MOODS.includes(data.mood) ? data.mood : 'neutral';
+        const intensity = typeof data.intensity === 'number'
+            ? Math.max(0, Math.min(1, data.intensity))
+            : 0.7;
+
+        this._applyMood(mood, intensity, 'server');
+    }
+
+    /**
+     * Infer a mood from the LLM's response text using keyword rules.
+     * Falls back to 'neutral' if no rule matches above threshold.
+     * @param {string} text
+     */
+    _inferFromText(text) {
+        if (!text || typeof text !== 'string') return;
+
+        // Cancel any pending reset — we're about to speak
+        if (this._resetTimer) {
+            clearTimeout(this._resetTimer);
+            this._resetTimer = null;
+        }
+
+        const result = this._classify(text);
+
+        if (result.confidence >= INFERENCE_THRESHOLD) {
+            this._applyMood(result.mood, result.intensity, 'inference');
+        }
+        // If no signal, leave face as-is (VoiceSession already set 'neutral' on first delta)
+    }
+
+    /**
+     * Classify text against MOOD_RULES.
+     * @param {string} text
+     * @returns {{ mood: string, intensity: number, confidence: number }}
+     */
+    _classify(text) {
+        let bestMood = 'neutral';
+        let bestScore = 0;
+
+        for (const rule of MOOD_RULES) {
+            let matchCount = 0;
+            for (const pattern of rule.patterns) {
+                if (pattern.test(text)) {
+                    matchCount++;
+                }
+            }
+            if (matchCount > 0) {
+                // Score = matchCount / total patterns (normalised 0–1)
+                const score = matchCount / rule.patterns.length;
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestMood = rule.mood;
+                }
+            }
+        }
+
+        // Intensity scales with how many signals fired
+        const intensity = 0.4 + bestScore * 0.6;
+        return { mood: bestMood, intensity, confidence: bestScore };
+    }
+
+    /**
+     * Apply a mood to the FaceManager and emit 'emotion:change'.
+     * @param {string} mood
+     * @param {number} intensity
+     * @param {string} source  'server' | 'inference' | 'manual'
+     */
+    _applyMood(mood, intensity, source) {
+        mood = VALID_MOODS.includes(mood) ? mood : 'neutral';
+
+        this._currentMood = mood;
+        this._currentIntensity = intensity;
+
+        faceManager.setMood(mood);
+
+        eventBus.emit('emotion:change', { mood, intensity, source });
+
+        console.log(`[EmotionEngine] Mood → ${mood} (intensity=${intensity.toFixed(2)}, src=${source})`);
+    }
+
+    /**
+     * Schedule a return to neutral after TTS ends.
+     * Cancelled if a new emotion comes in first.
+     */
+    _scheduleReset() {
+        if (this._resetTimer) clearTimeout(this._resetTimer);
+        this._resetTimer = setTimeout(() => {
+            this._resetTimer = null;
+            this._applyMood('neutral', 0.5, 'reset');
+        }, 1500);
+    }
+}
+
+// Singleton
+export const emotionEngine = new EmotionEngine();

package/src/core/EventBridge.js

@@ -0,0 +1,180 @@
+/**
+ * EventBridge — Multi-Agent Framework event bus (P6-T1)
+ *
+ * The ONLY coupling point between the app shell and agent adapters.
+ * Shell modules and adapters communicate exclusively through this bridge.
+ *
+ * Ref: future-dev-plans/17-MULTI-AGENT-FRAMEWORK.md
+ *
+ * Usage:
+ *   import { bridge, AgentEvents, AgentActions } from './EventBridge.js';
+ *
+ *   // Adapter emits:
+ *   bridge.emit(AgentEvents.CONNECTED);
+ *   bridge.emit(AgentEvents.STATE_CHANGED, { state: 'speaking' });
+ *
+ *   // Shell subscribes:
+ *   const unsub = bridge.on(AgentEvents.MOOD, ({ mood }) => FaceModule.setMood(mood));
+ *
+ *   // UI triggers agent action:
+ *   bridge.emit(AgentActions.SEND_MESSAGE, { text: 'Hello' });
+ */
+
+// ─────────────────────────────────────────────
+// Agent → UI Events (things the agent tells the UI)
+// ─────────────────────────────────────────────
+
+export const AgentEvents = {
+    // Connection lifecycle
+    CONNECTED:      'agent:connected',       // Agent is ready
+    DISCONNECTED:   'agent:disconnected',    // Agent disconnected
+    ERROR:          'agent:error',           // { message, code }
+
+    // Conversation state
+    STATE_CHANGED:  'agent:state',           // { state: 'speaking'|'listening'|'idle'|'thinking' }
+
+    // Content
+    MESSAGE:        'agent:message',         // { role: 'user'|'assistant', text, final: bool }
+    TRANSCRIPT:     'agent:transcript',      // { text, partial: bool } — live STT
+
+    // Audio signals (NOT the audio itself — each adapter handles its own audio)
+    TTS_PLAYING:    'agent:tts_playing',     // TTS audio started (for mouth animation)
+    TTS_STOPPED:    'agent:tts_stopped',     // TTS audio ended
+    AUDIO_LEVEL:    'agent:audio_level',     // { level: 0-1 } for waveform mouth
+
+    // Capabilities
+    MOOD:           'agent:mood',            // { mood: 'happy'|'thinking'|'sad'|'neutral'|'listening' }
+    CANVAS_CMD:     'agent:canvas',          // { action: 'present'|'close', url }
+    TOOL_CALLED:    'agent:tool',            // { name, params, result } for ActionConsole
+
+    // Music integration
+    MUSIC_PLAY:     'agent:music_play',      // { track?, action: 'play'|'skip'|'stop'|'pause' }
+    MUSIC_SYNC:     'agent:music_sync',      // Trigger syncMusicWithServer()
+
+    // Sound effects
+    PLAY_SOUND:     'agent:play_sound',      // { sound: 'air_horn', type: 'dj'|'caller' }
+
+    // Caller effect
+    CALLER_EFFECT:  'agent:caller_effect',   // { enabled: bool }
+
+    // Commercial
+    COMMERCIAL:     'agent:commercial',      // { action: 'play' }
+};
+
+// ─────────────────────────────────────────────
+// UI → Agent Actions (things the UI tells the agent)
+// ─────────────────────────────────────────────
+
+export const AgentActions = {
+    SEND_MESSAGE:   'ui:send_message',       // { text }
+    END_SESSION:    'ui:end_session',
+    CONTEXT_UPDATE: 'ui:context_update',     // { text } — background info injected silently
+    FORCE_MESSAGE:  'ui:force_message',      // { text } — SYSTEM messages agent must act on
+    MODE_SWITCH:    'ui:mode_switch',        // { mode } — switching agent mode
+};
+
+// ─────────────────────────────────────────────
+// EventBridge class
+// ─────────────────────────────────────────────
+
+class EventBridge {
+    constructor() {
+        /** @type {Object.<string, Function[]>} */
+        this._handlers = {};
+    }
+
+    /**
+     * Subscribe to an event.
+     * @param {string} event
+     * @param {Function} handler
+     * @returns {Function} unsubscribe function
+     */
+    on(event, handler) {
+        if (!this._handlers[event]) this._handlers[event] = [];
+        this._handlers[event].push(handler);
+        // Return unsubscribe function
+        return () => this.off(event, handler);
+    }
+
+    /**
+     * Unsubscribe a specific handler from an event.
+     * @param {string} event
+     * @param {Function} handler
+     */
+    off(event, handler) {
+        if (this._handlers[event]) {
+            this._handlers[event] = this._handlers[event].filter(h => h !== handler);
+            if (this._handlers[event].length === 0) {
+                delete this._handlers[event];
+            }
+        }
+    }
+
+    /**
+     * Subscribe to an event for one invocation only.
+     * @param {string} event
+     * @param {Function} handler
+     * @returns {Function} unsubscribe function
+     */
+    once(event, handler) {
+        const wrapper = (data) => {
+            handler(data);
+            this.off(event, wrapper);
+        };
+        return this.on(event, wrapper);
+    }
+
+    /**
+     * Emit an event to all registered handlers.
+     * Handler errors are caught and logged so one bad handler can't break others.
+     * @param {string} event
+     * @param {*} [data={}]
+     */
+    emit(event, data = {}) {
+        const handlers = this._handlers[event];
+        if (!handlers || handlers.length === 0) return;
+        // Snapshot array in case a handler modifies the list during dispatch
+        [...handlers].forEach(h => {
+            try {
+                h(data);
+            } catch (e) {
+                console.error(`[EventBridge] Error in "${event}" handler:`, e);
+            }
+        });
+    }
+
+    /**
+     * Clear all handlers for a specific event.
+     * Used during targeted cleanup (e.g. removing canvas listeners only).
+     * @param {string} event
+     */
+    clearEvent(event) {
+        delete this._handlers[event];
+    }
+
+    /**
+     * Clear ALL handlers — nuclear option for mode switching.
+     * Called by AgentOrchestrator when switching adapters to guarantee
+     * no stale handlers from the previous adapter survive.
+     */
+    clearAll() {
+        this._handlers = {};
+    }
+
+    /**
+     * Return list of events that currently have listeners (for debugging).
+     * @returns {string[]}
+     */
+    events() {
+        return Object.keys(this._handlers);
+    }
+}
+
+// ─────────────────────────────────────────────
+// Singleton — one bridge for the whole app
+// ─────────────────────────────────────────────
+
+export const bridge = new EventBridge();
+
+// Also export the class for testing / multiple instances
+export { EventBridge };