openvoiceui 1.0.0

package/src/shell/music-bridge.js

@@ -0,0 +1,60 @@
+/**
+ * music-bridge.js — Connect MusicModule to EventBridge (P6-T4)
+ *
+ * Handles music play/pause/stop/skip, volume ducking during speech,
+ * and DJ track-ending notifications back to the agent.
+ *
+ * Ref: future-dev-plans/17-MULTI-AGENT-FRAMEWORK.md (App Shell section)
+ */
+
+import { AgentEvents, AgentActions } from '../core/EventBridge.js';
+
+/**
+ * Wire MusicModule to the EventBridge.
+ * @param {import('../core/EventBridge.js').EventBridge} bridge
+ * @returns {Function[]} unsubscribe functions
+ */
+export function connectMusic(bridge) {
+    const music = () => window.musicPlayer;
+
+    const unsubs = [
+        // Agent-driven music control
+        bridge.on(AgentEvents.MUSIC_PLAY, ({ action, track }) => {
+            if (!music()) return;
+            if (action === 'stop')  music().stop?.();
+            else if (action === 'pause') music().pause?.();
+            else if (action === 'play')  music().play?.(track);
+            else if (action === 'skip')  music().next?.();
+        }),
+
+        // Agent triggers server-side music sync
+        bridge.on(AgentEvents.MUSIC_SYNC, () => {
+            window.syncMusicWithServer?.();
+        }),
+
+        // Volume ducking when agent speaks
+        bridge.on(AgentEvents.STATE_CHANGED, ({ state }) => {
+            music()?.duck?.(state === 'speaking');
+        }),
+    ];
+
+    // DJ track-ending notifications (tell agent when track is ending)
+    if (music()) {
+        music().onTrackEnding = (trackName, secondsLeft) => {
+            bridge.emit(AgentActions.CONTEXT_UPDATE, {
+                text: `[DJ INFO: "${trackName}" has ${secondsLeft}s left]`,
+            });
+            bridge.emit(AgentActions.FORCE_MESSAGE, {
+                text: `[SYSTEM: Song ending! Announce next track and call play_music action=skip!]`,
+            });
+        };
+
+        music().onTrackEnded = (trackName) => {
+            bridge.emit(AgentActions.FORCE_MESSAGE, {
+                text: `[SYSTEM: "${trackName}" ended! Call play_music action=skip NOW!]`,
+            });
+        };
+    }
+
+    return unsubs;
+}

package/src/shell/orchestrator.js

@@ -0,0 +1,233 @@
+/**
+ * orchestrator.js — AgentOrchestrator: capability-driven mode switching (P6-T4)
+ *
+ * The AgentOrchestrator manages registered agent adapters and handles
+ * mode switching with full cleanup + capability-driven UI updates.
+ *
+ * Key responsibilities:
+ *  - Register adapters with their configs
+ *  - Switch modes: destroy old adapter, clear bridge, init new adapter
+ *  - Connect shell bridge modules based on adapter capabilities
+ *  - Show/hide UI elements based on what the active adapter supports
+ *  - Persist selected mode in localStorage
+ *
+ * Ref: future-dev-plans/17-MULTI-AGENT-FRAMEWORK.md (Mode Switching section)
+ *
+ * Usage:
+ *   import { orchestrator } from './shell/orchestrator.js';
+ *   import { MyAdapter } from './adapters/my-adapter.js';
+ *
+ *   orchestrator.register('my-adapter', MyAdapter, { serverUrl: '...' });
+ *   await orchestrator.switchMode('my-adapter');
+ *   await orchestrator.startConversation();
+ */
+
+import { bridge } from '../core/EventBridge.js';
+import { connectFace }            from './face-bridge.js';
+import { connectMusic }           from './music-bridge.js';
+import { connectSounds }          from './sounds-bridge.js';
+import { connectCallerEffect }    from './caller-bridge.js';
+import { connectCanvas }          from './canvas-bridge.js';
+import { connectTranscript, connectActionConsole } from './transcript-bridge.js';
+import { connectWaveform }        from './waveform-bridge.js';
+import { connectCommercial }      from './commercial-bridge.js';
+import { connectCamera }          from './camera-bridge.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Capability → UI element map
+// Maps capability string → array of DOM element IDs to show when present.
+// Elements NOT in any capability's list are hidden by default.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CAPABILITY_UI_MAP = {
+    canvas:         ['canvas-button'],
+    music:          ['music-button'],
+    wake_word:      ['wake-button'],
+    camera:         ['camera-button'],
+    caller_effects: ['caller-effect-toggle'],
+    dj_soundboard:  [],   // no dedicated button, soundboard is always-present
+    face_panel:     ['face-button'],
+};
+
+// All capability-controlled element IDs (used to hide everything first)
+const ALL_CAPABILITY_ELEMENTS = [
+    ...new Set(Object.values(CAPABILITY_UI_MAP).flat()),
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AgentOrchestrator
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AgentOrchestrator {
+    constructor() {
+        /** @type {Object.<string, {adapter: object, config: object}>} */
+        this._adapters = {};
+
+        /** @type {object|null} */
+        this._activeAdapter = null;
+
+        /** @type {string|null} */
+        this._activeMode = null;
+
+        /** @type {Function[]} shell bridge unsubscribe functions */
+        this._shellConnections = [];
+    }
+
+    /**
+     * Register an adapter with its default config.
+     * Must be called before switchMode() can select this adapter.
+     *
+     * @param {string} mode - Unique mode key (e.g. 'clawdbot', 'elevenlabs-classic')
+     * @param {object} adapter - Adapter object with init/start/stop/destroy methods
+     * @param {object} config  - Adapter-specific configuration
+     */
+    register(mode, adapter, config = {}) {
+        this._adapters[mode] = { adapter, config };
+        console.log(`[Orchestrator] Registered adapter: ${mode}`);
+    }
+
+    /**
+     * Switch the active agent adapter.
+     * Performs full teardown of the current adapter, clears all bridge
+     * handlers, initialises the new adapter, reconnects shell bridges,
+     * and updates UI visibility based on the new adapter's capabilities.
+     *
+     * @param {string} newMode - Mode key to switch to
+     * @param {object} [configOverride] - Optional config overrides for this switch
+     */
+    async switchMode(newMode, configOverride = {}) {
+        const entry = this._adapters[newMode];
+        if (!entry) {
+            console.error(`[Orchestrator] Unknown mode: ${newMode}`);
+            throw new Error(`Unknown agent mode: ${newMode}`);
+        }
+
+        // 1. Tear down current adapter completely
+        if (this._activeAdapter) {
+            console.log(`[Orchestrator] Destroying ${this._activeMode}`);
+            try {
+                await this._activeAdapter.destroy();
+            } catch (e) {
+                console.warn('[Orchestrator] Error during adapter destroy:', e);
+            }
+        }
+
+        // 2. Disconnect all shell bridge subscriptions (prevent stale handlers)
+        this._shellConnections.forEach(unsub => {
+            try { unsub(); } catch (e) { /* ignore */ }
+        });
+        this._shellConnections = [];
+
+        // 3. Clear ALL bridge handlers (nuclear clear — guarantees no leaks)
+        bridge.clearAll();
+
+        // 4. Initialise new adapter
+        console.log(`[Orchestrator] Initialising ${newMode}`);
+        this._activeAdapter = entry.adapter;
+        this._activeMode = newMode;
+
+        const config = { ...entry.config, ...configOverride };
+        await entry.adapter.init(bridge, config);
+
+        // 5. Reconnect shell modules (always-on bridges)
+        const caps = entry.adapter.capabilities || [];
+
+        this._shellConnections.push(
+            ...connectFace(bridge),
+            ...connectWaveform(bridge),
+            ...connectTranscript(bridge),
+            ...connectActionConsole(bridge),
+            ...connectMusic(bridge),
+            ...connectSounds(bridge),
+        );
+
+        // 6. Conditional bridges — only connect when adapter has the capability
+        this._shellConnections.push(
+            ...connectCallerEffect(bridge, caps),
+            ...connectCanvas(bridge, caps),
+            ...connectCommercial(bridge, caps),
+            ...connectCamera(bridge, caps),
+        );
+
+        // 7. Update UI visibility based on capabilities
+        this._updateFeatureUI(caps);
+
+        // 8. Persist selection
+        try { localStorage.setItem('agent_mode', newMode); } catch (e) { /* ignore */ }
+
+        console.log(`[Orchestrator] Mode switched to: ${newMode} (caps: [${caps.join(', ')}])`);
+    }
+
+    /**
+     * Start a conversation with the active adapter.
+     */
+    async startConversation() {
+        if (!this._activeAdapter) {
+            console.warn('[Orchestrator] No active adapter — call switchMode() first');
+            return;
+        }
+        await this._activeAdapter.start();
+    }
+
+    /**
+     * Stop the active conversation (but keep adapter alive).
+     */
+    async stopConversation() {
+        if (this._activeAdapter) {
+            await this._activeAdapter.stop();
+        }
+    }
+
+    /**
+     * Return the active adapter's capability list.
+     * @returns {string[]}
+     */
+    get capabilities() {
+        return this._activeAdapter?.capabilities ?? [];
+    }
+
+    /**
+     * Return the active mode key.
+     * @returns {string|null}
+     */
+    get activeMode() {
+        return this._activeMode;
+    }
+
+    /**
+     * Show/hide UI elements based on what the active adapter supports.
+     * Capability-controlled elements are hidden first, then shown for
+     * each capability the adapter declares.
+     *
+     * @param {string[]} capabilities - Capabilities of the active adapter
+     * @private
+     */
+    _updateFeatureUI(capabilities) {
+        // Hide all capability-controlled elements first
+        ALL_CAPABILITY_ELEMENTS.forEach(id => {
+            const el = document.getElementById(id);
+            if (el) el.style.display = 'none';
+        });
+
+        // Show elements for each declared capability
+        capabilities.forEach(cap => {
+            const ids = CAPABILITY_UI_MAP[cap] ?? [];
+            ids.forEach(id => {
+                const el = document.getElementById(id);
+                if (el) el.style.display = '';
+            });
+        });
+
+        // Emit capability list for any shell components that inspect it
+        console.log(`[Orchestrator] UI updated for capabilities: [${capabilities.join(', ')}]`);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Singleton — one orchestrator for the whole app
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const orchestrator = new AgentOrchestrator();
+
+// Also export class for testing
+export { AgentOrchestrator };

package/src/shell/profile-discovery.js

@@ -0,0 +1,303 @@
+/**
+ * profile-discovery.js — Adapter auto-discovery from profiles (P6-T5)
+ *
+ * ProfileDiscovery fetches agent profiles from the server, resolves which
+ * adapter each profile requires, registers every profile as an orchestrator
+ * mode, and activates the initial mode (from localStorage or server default).
+ *
+ * This implements the "plug-and-play" promise from the multi-agent framework:
+ *   Adding a new agent = 1 adapter file + 1 profile JSON entry.
+ *   ProfileDiscovery does the rest automatically.
+ *
+ * Integration:
+ *   1. Call `await profileDiscovery.init({ serverUrl })` at app startup.
+ *   2. All profiles → orchestrator modes are registered automatically.
+ *   3. ProfileSwitcher's 'profile:switched' event triggers adapter hot-swap.
+ *
+ * Ref: future-dev-plans/17-MULTI-AGENT-FRAMEWORK.md
+ *      "Adding a New Agent System (The Plug-and-Play Promise)"
+ *
+ * Usage:
+ *   import { profileDiscovery } from './profile-discovery.js';
+ *   await profileDiscovery.init({ serverUrl: 'http://localhost:5001' });
+ *   // Orchestrator is now registered with all adapters — call switchMode, start, etc.
+ */
+
+import { orchestrator }    from './orchestrator.js';
+import { adapterRegistry } from './adapter-registry.js';
+import { eventBus }        from '../core/EventBus.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ProfileDiscovery
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ProfileDiscovery {
+    constructor() {
+        /** @type {string} */
+        this._serverUrl = '';
+
+        /** @type {object[]} — Raw profile objects from /api/profiles */
+        this._profiles = [];
+
+        /** @type {string|null} — Active profile ID reported by the server */
+        this._serverActiveId = null;
+
+        /** @type {boolean} */
+        this._initialized = false;
+    }
+
+    // ── Public API ────────────────────────────────────────────────────────────
+
+    /**
+     * Fetch profiles, load adapter modules, register each profile as an
+     * orchestrator mode, and activate the initial mode.
+     *
+     * Errors in individual adapter registrations are non-fatal: other adapters
+     * are still registered. A total failure falls back to the clawdbot adapter.
+     *
+     * @param {object}  options
+     * @param {string}  options.serverUrl      - Base URL of the backend
+     * @param {string} [options.fallbackMode]  - Adapter ID used if everything fails
+     */
+    async init({ serverUrl = '', fallbackMode = 'clawdbot' } = {}) {
+        this._serverUrl = serverUrl;
+
+        try {
+            await this._fetchProfiles();
+            await this._registerAllAdapters();
+            await this._activateInitialMode(fallbackMode);
+        } catch (err) {
+            console.error('[ProfileDiscovery] Init failed:', err);
+            // Best-effort fallback: register and activate clawdbot directly
+            try {
+                await this._registerFallback(fallbackMode);
+                await orchestrator.switchMode(fallbackMode);
+            } catch (e) {
+                console.error('[ProfileDiscovery] Fallback registration also failed:', e);
+            }
+        }
+
+        this._initialized = true;
+
+        // Listen for profile-switch events emitted by ProfileSwitcher UI
+        eventBus.on('profile:switched', (d) => this._onProfileSwitched(d.profile));
+
+        console.log('[ProfileDiscovery] Initialised. Known modes:', Object.keys(orchestrator._adapters));
+    }
+
+    /**
+     * Return the raw profile list fetched from the server.
+     * @returns {object[]}
+     */
+    get profiles() {
+        return this._profiles;
+    }
+
+    /**
+     * Return the currently active profile ID.
+     * Reads from the orchestrator's active mode (source of truth at runtime).
+     * @returns {string|null}
+     */
+    get activeId() {
+        return orchestrator.activeMode;
+    }
+
+    /**
+     * Return true after init() has completed (successfully or via fallback).
+     * @returns {boolean}
+     */
+    get initialized() {
+        return this._initialized;
+    }
+
+    // ── Private: bootstrap ────────────────────────────────────────────────────
+
+    /**
+     * Fetch /api/profiles and store the result.
+     * @private
+     */
+    async _fetchProfiles() {
+        const resp = await fetch(`${this._serverUrl}/api/profiles`);
+        if (!resp.ok) {
+            throw new Error(`/api/profiles returned HTTP ${resp.status}`);
+        }
+        const data = await resp.json();
+        this._profiles      = data.profiles || [];
+        this._serverActiveId = data.active   || null;
+
+        console.log(
+            `[ProfileDiscovery] Fetched ${this._profiles.length} profile(s),`,
+            `server active: "${this._serverActiveId}"`
+        );
+    }
+
+    /**
+     * For each profile, dynamically import its adapter and register the
+     * profile as an orchestrator mode.
+     *
+     * Profile → orchestrator mode mapping:
+     *   - mode key  = profile.id            (e.g. 'default', 'hume-evi')
+     *   - adapter   = profile.adapter       (e.g. 'clawdbot', 'hume-evi')
+     *   - config    = profile.adapter_config (adapter-specific params from JSON)
+     *     plus serverUrl and profileId injected automatically.
+     *
+     * Adapter modules are cached by AdapterRegistry, so multiple profiles
+     * sharing the same adapter (e.g. three ClawdBot profiles) only trigger
+     * one dynamic import.
+     *
+     * @private
+     */
+    async _registerAllAdapters() {
+        for (const profile of this._profiles) {
+            const adapterId = profile.adapter || adapterRegistry.defaultAdapter;
+            const modeKey   = profile.id;
+            const config    = {
+                ...(profile.adapter_config || {}),
+                // Always inject serverUrl so adapters don't need to hardcode it
+                serverUrl:  (profile.adapter_config?.serverUrl) || this._serverUrl,
+                // profileId lets adapters read the full profile server-side if needed
+                profileId: profile.id,
+            };
+
+            try {
+                const adapter = await adapterRegistry.load(adapterId);
+                orchestrator.register(modeKey, adapter, config);
+                console.log(
+                    `[ProfileDiscovery] Registered mode "${modeKey}"`,
+                    `→ adapter "${adapterId}"`
+                );
+            } catch (err) {
+                console.warn(
+                    `[ProfileDiscovery] Could not register mode "${modeKey}"`,
+                    `(adapter "${adapterId}"):`, err.message
+                );
+                // Continue with remaining profiles — non-fatal
+            }
+        }
+    }
+
+    /**
+     * Decide which mode to activate at startup.
+     *
+     * Priority:
+     *   1. localStorage 'agent_mode' (user's last manual selection)
+     *   2. Server-reported active profile
+     *   3. fallbackMode parameter
+     *
+     * @param {string} fallbackMode
+     * @private
+     */
+    async _activateInitialMode(fallbackMode) {
+        const saved  = this._readSavedMode();
+        const target = saved || this._serverActiveId || fallbackMode;
+
+        // Make sure target mode is registered (saved mode might be stale)
+        const registered = Object.keys(orchestrator._adapters);
+        const resolvedTarget = registered.includes(target)
+            ? target
+            : (this._serverActiveId || fallbackMode);
+
+        if (resolvedTarget !== target) {
+            console.warn(
+                `[ProfileDiscovery] Saved mode "${target}" not registered;`,
+                `falling back to "${resolvedTarget}"`
+            );
+        }
+
+        try {
+            await orchestrator.switchMode(resolvedTarget);
+        } catch (err) {
+            console.error(
+                `[ProfileDiscovery] Could not activate mode "${resolvedTarget}":`, err
+            );
+            // Last resort: try the raw fallback
+            if (resolvedTarget !== fallbackMode && registered.includes(fallbackMode)) {
+                await orchestrator.switchMode(fallbackMode);
+            }
+        }
+    }
+
+    /**
+     * Register the fallback adapter without needing a profile entry.
+     * Used when _fetchProfiles fails entirely.
+     * @param {string} adapterId
+     * @private
+     */
+    async _registerFallback(adapterId) {
+        const adapter = await adapterRegistry.load(adapterId);
+        orchestrator.register(adapterId, adapter, { serverUrl: this._serverUrl });
+        console.log(`[ProfileDiscovery] Registered fallback mode "${adapterId}"`);
+    }
+
+    /**
+     * Read the saved agent mode from localStorage, returning null on error.
+     * @returns {string|null}
+     * @private
+     */
+    _readSavedMode() {
+        try {
+            return localStorage.getItem('agent_mode') || null;
+        } catch (_) {
+            return null;
+        }
+    }
+
+    // ── Private: runtime profile switching ───────────────────────────────────
+
+    /**
+     * Called when the ProfileSwitcher UI emits 'profile:switched'.
+     * Switches the orchestrator to the new profile's adapter mode.
+     *
+     * If the new profile was not in the initial fetch (e.g. dynamically
+     * created), it is registered on-the-fly before switching.
+     *
+     * @param {object} profile - The newly-activated profile object from the server
+     * @private
+     */
+    async _onProfileSwitched(profile) {
+        if (!profile?.id) return;
+
+        const modeKey   = profile.id;
+        const adapterId = profile.adapter || adapterRegistry.defaultAdapter;
+
+        console.log(
+            `[ProfileDiscovery] 'profile:switched' → mode "${modeKey}"`,
+            `adapter "${adapterId}"`
+        );
+
+        // Register on-the-fly if not already known (handles dynamically-created profiles)
+        if (!orchestrator._adapters[modeKey]) {
+            try {
+                const adapter = await adapterRegistry.load(adapterId);
+                orchestrator.register(modeKey, adapter, {
+                    ...(profile.adapter_config || {}),
+                    serverUrl: this._serverUrl,
+                    profileId: profile.id,
+                });
+                console.log(`[ProfileDiscovery] On-the-fly registered mode "${modeKey}"`);
+            } catch (err) {
+                console.error(
+                    `[ProfileDiscovery] Failed to register mode "${modeKey}" on-the-fly:`, err
+                );
+                return;
+            }
+        }
+
+        try {
+            await orchestrator.switchMode(modeKey);
+        } catch (err) {
+            console.error(
+                `[ProfileDiscovery] Failed to switch orchestrator to "${modeKey}":`, err
+            );
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Singleton
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const profileDiscovery = new ProfileDiscovery();
+
+// Also export class for testing
+export { ProfileDiscovery };

package/src/shell/sounds-bridge.js

@@ -0,0 +1,28 @@
+/**
+ * sounds-bridge.js — Connect DJ/caller sounds to EventBridge (P6-T4)
+ *
+ * Routes PLAY_SOUND events to the DJ soundboard or caller sound player.
+ *
+ * Ref: future-dev-plans/17-MULTI-AGENT-FRAMEWORK.md (App Shell section)
+ */
+
+import { AgentEvents } from '../core/EventBridge.js';
+
+/**
+ * Wire sound effects to the EventBridge.
+ * @param {import('../core/EventBridge.js').EventBridge} bridge
+ * @returns {Function[]} unsubscribe functions
+ */
+export function connectSounds(bridge) {
+    const unsubs = [
+        bridge.on(AgentEvents.PLAY_SOUND, ({ sound, type }) => {
+            if (type === 'dj') {
+                window.DJSoundboard?.play(sound);
+            } else if (type === 'caller') {
+                window.playCallerSound?.(sound);
+            }
+        }),
+    ];
+
+    return unsubs;
+}

package/src/shell/transcript-bridge.js

@@ -0,0 +1,61 @@
+/**
+ * transcript-bridge.js — Connect TranscriptPanel and ActionConsole to EventBridge (P6-T4)
+ *
+ * Routes message/transcript events to the transcript panel and
+ * tool/lifecycle events to the action console.
+ *
+ * Ref: future-dev-plans/17-MULTI-AGENT-FRAMEWORK.md (App Shell section)
+ */
+
+import { AgentEvents } from '../core/EventBridge.js';
+
+/**
+ * Wire TranscriptPanel to the EventBridge.
+ * @param {import('../core/EventBridge.js').EventBridge} bridge
+ * @returns {Function[]} unsubscribe functions
+ */
+export function connectTranscript(bridge) {
+    const tp = () => window.TranscriptPanel;
+
+    const unsubs = [
+        bridge.on(AgentEvents.MESSAGE, ({ role, text, final }) => {
+            if (!tp()) return;
+            if (final) tp().addMessage(role, text);
+            else tp().updateStreaming?.(text);
+        }),
+        bridge.on(AgentEvents.TRANSCRIPT, ({ text }) => {
+            tp()?.updateStreaming?.(text);
+        }),
+    ];
+
+    return unsubs;
+}
+
+/**
+ * Wire ActionConsole to the EventBridge.
+ * @param {import('../core/EventBridge.js').EventBridge} bridge
+ * @returns {Function[]} unsubscribe functions
+ */
+export function connectActionConsole(bridge) {
+    const ac = () => window.ActionConsole;
+
+    const unsubs = [
+        bridge.on(AgentEvents.TOOL_CALLED, ({ name, result }) => {
+            ac()?.addEntry('tool', name, JSON.stringify(result ?? ''));
+        }),
+        bridge.on(AgentEvents.CONNECTED, () => {
+            ac()?.addEntry('lifecycle', 'Agent connected');
+        }),
+        bridge.on(AgentEvents.DISCONNECTED, () => {
+            ac()?.addEntry('lifecycle', 'Agent disconnected');
+        }),
+        bridge.on(AgentEvents.ERROR, ({ message }) => {
+            ac()?.addEntry('error', `Agent error: ${message}`);
+        }),
+        bridge.on(AgentEvents.STATE_CHANGED, ({ state }) => {
+            ac()?.addEntry('system', `State: ${state}`);
+        }),
+    ];
+
+    return unsubs;
+}