@elizaos/agent 0.25.8 → 2.0.0-alpha.83

package/packages/agent/src/api/stream-routes.js

@@ -0,0 +1,809 @@
+/**
+ * Generic streaming infrastructure routes.
+ *
+ * Extracted from retake-routes.ts so any streaming destination (Retake.tv,
+ * custom RTMP, etc.) can reuse the same pipeline: capture mode detection,
+ * Xvfb management, browser capture, FFmpeg, frame routing, volume/mute.
+ *
+ * Platform-specific credential fetching lives in destination adapters
+ * (e.g. retake-routes.ts exports `createRetakeDestination`).
+ */
+import fs from "node:fs";
+import { logger } from "@elizaos/core";
+import { getTtsProviderStatus, resolveTtsConfig, ttsStreamBridge, } from "../services/tts-stream-bridge";
+import { sanitizeSpeechText } from "../utils/spoken-text";
+import { readRequestBody, readRequestBodyBuffer, sendJson, sendJsonError, } from "./http-helpers";
+import { getHeadlessCaptureConfig, parseDestinationQuery, readOverlayLayout, readStreamSettings, seedOverlayDefaults, validateStreamSettings, writeOverlayLayout, writeStreamSettings, } from "./stream-persistence";
+import { handleStreamVoiceRoute as handleAutonomousStreamVoiceRoute, onAgentMessage as onAutonomousAgentMessage, } from "./stream-voice-routes";
+// ---------------------------------------------------------------------------
+// MJPEG frame store — shared state for GET /api/stream/screen
+// ---------------------------------------------------------------------------
+/**
+ * Stores the most-recently received JPEG frame and pushes each new frame
+ * to all active MJPEG subscribers (GET /api/stream/screen).
+ *
+ * Frames arrive via POST /api/stream/frame from:
+ *  - Electrobun screencapture module (JS canvas → JPEG)
+ *  - Legacy desktop screencapture bridges
+ *  - Any client POSTing raw JPEG bytes
+ */
+const MJPEG_BOUNDARY = "elizaframe";
+const mjpegSubscribers = new Set();
+let latestFrame = null;
+function pushFrameToSubscribers(frame) {
+    latestFrame = frame;
+    if (mjpegSubscribers.size === 0)
+        return;
+    const header = `--${MJPEG_BOUNDARY}\r\nContent-Type: image/jpeg\r\nContent-Length: ${frame.length}\r\n\r\n`;
+    const headerBuf = Buffer.from(header, "ascii");
+    const trailer = Buffer.from("\r\n", "ascii");
+    const chunk = Buffer.concat([headerBuf, frame, trailer]);
+    for (const sub of mjpegSubscribers) {
+        try {
+            sub.write(chunk);
+        }
+        catch {
+            mjpegSubscribers.delete(sub);
+        }
+    }
+}
+/** Resolve the active streaming destination from the registry. */
+export function getActiveDestination(state) {
+    if (state.activeDestinationId) {
+        return state.destinations.get(state.activeDestinationId);
+    }
+    // Fallback: first destination in map (backward compat for single-destination configs)
+    const first = state.destinations.values().next();
+    return first.done ? undefined : first.value;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function json(res, data, status = 200) {
+    sendJson(res, data, status);
+}
+function error(res, message, status) {
+    sendJsonError(res, message, status);
+}
+function resolveRouteTtsConfig(config) {
+    return resolveTtsConfig(config);
+}
+function getRouteTtsProviderStatus(config) {
+    return getTtsProviderStatus(config);
+}
+const ttsBridgeAdapter = {
+    isSpeaking() {
+        return ttsStreamBridge.isSpeaking();
+    },
+    isAttached() {
+        return ttsStreamBridge.isAttached();
+    },
+    async speak(text, config) {
+        return ttsStreamBridge.speak(text, config);
+    },
+};
+function readRouteStreamSettings() {
+    return readStreamSettings();
+}
+function writeRouteStreamSettings(settings) {
+    writeStreamSettings(settings);
+}
+// ---------------------------------------------------------------------------
+// Capture mode detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect the best capture mode for the current environment.
+ *
+ * Priority:
+ * 1. STREAM_MODE / RETAKE_STREAM_MODE env var (explicit override)
+ * 2. Desktop screen capture bridge -> "pipe" (POST /api/stream/frame -> FFmpeg stdin)
+ * 3. Linux with DISPLAY or Xvfb -> "x11grab" (Hyperscape approach)
+ * 4. macOS -> "avfoundation" (native screen capture)
+ * 5. Fallback -> "file" (Puppeteer CDP -> temp JPEG -> FFmpeg)
+ */
+/** @internal Exported for testing. */
+export function detectCaptureMode() {
+    const explicit = process.env.STREAM_MODE ?? process.env.RETAKE_STREAM_MODE;
+    if (explicit === "ui" || explicit === "pipe")
+        return "pipe";
+    if (explicit === "x11grab")
+        return "x11grab";
+    if (explicit === "avfoundation" || explicit === "screen")
+        return "avfoundation";
+    if (explicit === "file")
+        return "file";
+    // Desktop bridge -> pipe mode
+    if ("__elizaScreenCapture" in globalThis) {
+        return "pipe";
+    }
+    // Linux with a display -> x11grab (Xvfb or native X11)
+    if (process.platform === "linux" && process.env.DISPLAY)
+        return "x11grab";
+    // macOS -> avfoundation screen capture
+    if (process.platform === "darwin")
+        return "avfoundation";
+    // Fallback -> headless browser capture -> file mode
+    return "file";
+}
+// ---------------------------------------------------------------------------
+// Xvfb management
+// ---------------------------------------------------------------------------
+/**
+ * Try to start Xvfb on the specified display if not already running (Linux only).
+ * Returns true if display is available, false otherwise.
+ */
+/** @internal Exported for testing. */
+export async function ensureXvfb(display, resolution) {
+    if (process.platform !== "linux")
+        return false;
+    // Validate display format to prevent command injection (must be :<digits>)
+    if (!/^:\d+$/.test(display)) {
+        logger.warn(`[stream] Invalid display format: ${display} (expected :<number>)`);
+        return false;
+    }
+    // Validate resolution early so callers get a clear failure before we
+    // touch the display or spawn processes.
+    const [w, h] = resolution.split("x");
+    if (!w || !h || !/^\d+$/.test(w) || !/^\d+$/.test(h)) {
+        logger.warn(`[stream] Invalid resolution for Xvfb: ${resolution}`);
+        return false;
+    }
+    // Check if the display is already active
+    if (process.env.DISPLAY === display)
+        return true;
+    try {
+        const { execSync } = await import("node:child_process");
+        // Check if Xvfb is already running on this display
+        try {
+            execSync(`xdpyinfo -display ${display}`, {
+                stdio: "ignore",
+                timeout: 3000,
+            });
+            logger.info(`[stream] Xvfb already running on display ${display}`);
+            return true;
+        }
+        catch {
+            // Not running -- start it
+        }
+        const { spawn: spawnProc } = await import("node:child_process");
+        const xvfb = spawnProc("Xvfb", [display, "-screen", "0", `${w}x${h}x24`, "-ac"], {
+            stdio: "ignore",
+            detached: true,
+        });
+        xvfb.unref();
+        // Wait for Xvfb to be ready
+        await new Promise((r) => setTimeout(r, 1000));
+        logger.info(`[stream] Started Xvfb on display ${display} (${resolution})`);
+        process.env.DISPLAY = display;
+        return true;
+    }
+    catch (err) {
+        logger.warn(`[stream] Failed to start Xvfb: ${err}`);
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Streaming pipeline (destination-driven)
+// ---------------------------------------------------------------------------
+/**
+ * Start the full streaming pipeline using the configured destination for
+ * RTMP credentials. Handles capture mode detection, Xvfb, browser capture,
+ * and FFmpeg configuration.
+ */
+async function startStreamPipeline(state, rtmpUrl, rtmpKey) {
+    // Defense-in-depth: validate RTMP scheme before passing to FFmpeg
+    if (!/^rtmps?:\/\//i.test(rtmpUrl)) {
+        throw new Error("RTMP URL must use rtmp:// or rtmps:// scheme");
+    }
+    // Seed plugin-default overlay layout on first stream start
+    const activeDest = getActiveDestination(state);
+    if (activeDest) {
+        seedOverlayDefaults(activeDest);
+    }
+    const destId = activeDest?.id ?? null;
+    const mode = detectCaptureMode();
+    // Check if stream voice (TTS) is enabled in settings
+    const streamSettings = readStreamSettings();
+    const voiceEnabled = streamSettings.voice?.enabled === true;
+    const ttsConfig = state.config?.messages?.tts;
+    const resolvedTts = voiceEnabled ? resolveTtsConfig(ttsConfig) : null;
+    const audioSource = resolvedTts
+        ? "tts"
+        : (process.env.STREAM_AUDIO_SOURCE ??
+            process.env.RETAKE_AUDIO_SOURCE ??
+            "silent");
+    const audioDevice = process.env.STREAM_AUDIO_DEVICE ?? process.env.RETAKE_AUDIO_DEVICE;
+    const volume = parseInt(process.env.STREAM_VOLUME ?? process.env.RETAKE_VOLUME ?? "80", 10);
+    const resolution = "1280x720";
+    const baseConfig = {
+        rtmpUrl,
+        rtmpKey,
+        resolution,
+        bitrate: "1500k",
+        audioSource,
+        audioDevice,
+        volume,
+    };
+    switch (mode) {
+        case "pipe": {
+            // Desktop UI mode: FFmpeg reads frames from stdin via writeFrame().
+            logger.info("[stream] Capture mode: pipe (desktop UI)");
+            await state.streamManager.start({
+                ...baseConfig,
+                inputMode: "pipe",
+                framerate: 15,
+            });
+            // Auto-start desktop frame capture so the UI is streamed without
+            // requiring a manual button click in the renderer.
+            if (state.screenCapture && !state.screenCapture.isFrameCaptureActive()) {
+                try {
+                    const captureOpts = {
+                        fps: 15,
+                        quality: 70,
+                        endpoint: "/api/stream/frame",
+                    };
+                    if (state.activeStreamSource.type !== "stream-tab" &&
+                        state.activeStreamSource.url) {
+                        captureOpts.gameUrl = state.activeStreamSource.url;
+                    }
+                    await state.screenCapture.startFrameCapture(captureOpts);
+                    logger.info("[stream] Auto-started desktop frame capture");
+                }
+                catch (err) {
+                    logger.warn(`[stream] Failed to auto-start frame capture: ${err}`);
+                }
+            }
+            else if (!state.screenCapture) {
+                logger.warn("[stream] ScreenCaptureManager not available -- frame capture must be started manually");
+            }
+            break;
+        }
+        case "x11grab": {
+            // Linux Xvfb mode (Hyperscape approach): capture virtual display.
+            const display = process.env.STREAM_DISPLAY ?? process.env.RETAKE_DISPLAY ?? ":99";
+            logger.info(`[stream] Capture mode: x11grab (display ${display})`);
+            // Ensure Xvfb is running
+            await ensureXvfb(display, resolution);
+            // Launch a browser on the virtual display so there's something to capture
+            const captureUrl = state.captureUrl ??
+                process.env.STREAM_CAPTURE_URL ??
+                process.env.RETAKE_CAPTURE_URL ??
+                `http://127.0.0.1:${state.port ?? 2138}`;
+            try {
+                const { startBrowserCapture } = await import("../services/browser-capture");
+                // Browser capture in x11grab mode just opens the browser on the display --
+                // we don't need the frame file since FFmpeg captures the display directly.
+                await startBrowserCapture({
+                    url: captureUrl,
+                    width: 1280,
+                    height: 720,
+                    quality: 70,
+                    ...getHeadlessCaptureConfig(destId),
+                });
+            }
+            catch (err) {
+                logger.warn(`[stream] Browser launch on ${display} failed: ${err}`);
+            }
+            await state.streamManager.start({
+                ...baseConfig,
+                inputMode: "x11grab",
+                display,
+                framerate: 30,
+            });
+            break;
+        }
+        case "avfoundation": {
+            // macOS native screen capture.
+            const videoDevice = process.env.STREAM_VIDEO_DEVICE ??
+                process.env.RETAKE_VIDEO_DEVICE ??
+                "3";
+            logger.info(`[stream] Capture mode: avfoundation (device ${videoDevice})`);
+            await state.streamManager.start({
+                ...baseConfig,
+                inputMode: "avfoundation",
+                videoDevice,
+                framerate: 30,
+            });
+            break;
+        }
+        default: {
+            // Headless browser capture -> temp JPEG file -> FFmpeg file mode.
+            const captureUrl = state.captureUrl ??
+                process.env.STREAM_CAPTURE_URL ??
+                process.env.RETAKE_CAPTURE_URL ??
+                `http://127.0.0.1:${state.port ?? 2138}`;
+            logger.info(`[stream] Capture mode: file (browser capture -> ${captureUrl})`);
+            const { startBrowserCapture, FRAME_FILE } = await import("../services/browser-capture");
+            try {
+                await startBrowserCapture({
+                    url: captureUrl,
+                    width: 1280,
+                    height: 720,
+                    quality: 70,
+                    ...getHeadlessCaptureConfig(destId),
+                });
+                // Wait for first frame file to be written
+                await new Promise((resolve) => {
+                    const check = setInterval(() => {
+                        try {
+                            if (fs.existsSync(FRAME_FILE) &&
+                                fs.statSync(FRAME_FILE).size > 0) {
+                                clearInterval(check);
+                                resolve(true);
+                            }
+                        }
+                        catch {
+                            // Frame file not yet ready -- poll again
+                        }
+                    }, 200);
+                    setTimeout(() => {
+                        clearInterval(check);
+                        resolve(false);
+                    }, 10_000);
+                });
+            }
+            catch (captureErr) {
+                logger.warn(`[stream] Browser capture failed: ${captureErr}`);
+            }
+            await state.streamManager.start({
+                ...baseConfig,
+                inputMode: "file",
+                frameFile: FRAME_FILE,
+                framerate: 30,
+            });
+            break;
+        }
+    }
+    return { inputMode: mode || "file", audioSource };
+}
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+/** Returns `true` if handled, `false` to fall through. */
+export async function handleStreamRoute(req, res, pathname, method, state) {
+    // Fast-path: skip if not a stream route
+    if (!pathname.startsWith("/api/stream/") &&
+        !pathname.startsWith("/api/streaming/")) {
+        return false;
+    }
+    // ── POST /api/stream/frame -- pipe frames to StreamManager + MJPEG ──
+    if (method === "POST" && pathname === "/api/stream/frame") {
+        try {
+            const buf = await readRequestBodyBuffer(req, {
+                maxBytes: 2 * 1024 * 1024,
+            });
+            if (!buf || buf.length === 0) {
+                error(res, "Empty frame", 400);
+                return true;
+            }
+            // Always store frame for MJPEG monitoring (GET /api/stream/screen)
+            pushFrameToSubscribers(buf);
+            // Write to FFmpeg only when RTMP streaming is active
+            if (state.streamManager.isRunning()) {
+                state.streamManager.writeFrame(buf);
+            }
+            res.writeHead(200);
+            res.end();
+        }
+        catch {
+            error(res, "Frame write failed", 500);
+        }
+        return true;
+    }
+    // ── GET /api/stream/screen -- MJPEG live view (local + remote agents) ─
+    // Serves a continuous multipart/x-mixed-replace stream of JPEG frames.
+    // Works independently of RTMP streaming — frames arrive via POST /api/stream/frame.
+    // Usage: <img src="http://agent-host:2138/api/stream/screen" />
+    if (method === "GET" && pathname === "/api/stream/screen") {
+        res.writeHead(200, {
+            "Content-Type": `multipart/x-mixed-replace; boundary=${MJPEG_BOUNDARY}`,
+            "Cache-Control": "no-store, no-cache",
+            Connection: "close",
+            "Access-Control-Allow-Origin": "*",
+        });
+        mjpegSubscribers.add(res);
+        // Send the latest cached frame immediately so there's no blank wait
+        if (latestFrame) {
+            const header = `--${MJPEG_BOUNDARY}\r\nContent-Type: image/jpeg\r\nContent-Length: ${latestFrame.length}\r\n\r\n`;
+            res.write(Buffer.concat([
+                Buffer.from(header, "ascii"),
+                latestFrame,
+                Buffer.from("\r\n", "ascii"),
+            ]));
+        }
+        const cleanup = () => {
+            mjpegSubscribers.delete(res);
+        };
+        req.on("close", cleanup);
+        req.on("error", cleanup);
+        res.on("close", cleanup);
+        res.on("error", cleanup);
+        // Keep the response open — frames are pushed as they arrive
+        return true;
+    }
+    // ── POST /api/stream/live -- start stream via destination ────────────
+    if (method === "POST" && pathname === "/api/stream/live") {
+        if (state.streamManager.isRunning()) {
+            const health = state.streamManager.getHealth();
+            json(res, {
+                ok: true,
+                live: true,
+                message: "Already streaming",
+                ...health,
+            });
+            return true;
+        }
+        const dest = getActiveDestination(state);
+        if (!dest) {
+            error(res, "No streaming destination configured", 400);
+            return true;
+        }
+        try {
+            const { rtmpUrl, rtmpKey } = await dest.getCredentials();
+            const { inputMode, audioSource } = await startStreamPipeline(state, rtmpUrl, rtmpKey);
+            await dest.onStreamStart?.();
+            json(res, {
+                ok: true,
+                live: true,
+                rtmpUrl,
+                inputMode,
+                audioSource,
+                destination: dest.id,
+            });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to go live", 500);
+        }
+        return true;
+    }
+    // ── POST /api/stream/offline -- stop stream + notify destination ─────
+    if (method === "POST" && pathname === "/api/stream/offline") {
+        try {
+            // Stop browser capture
+            try {
+                const { stopBrowserCapture } = await import("../services/browser-capture");
+                await stopBrowserCapture();
+            }
+            catch {
+                // Browser capture may not have been started -- ignore
+            }
+            // Stop StreamManager
+            if (state.streamManager.isRunning()) {
+                await state.streamManager.stop();
+            }
+            // Notify destination
+            try {
+                await getActiveDestination(state)?.onStreamStop?.();
+            }
+            catch {
+                // Destination notification failure is non-fatal
+            }
+            json(res, { ok: true, live: false });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to go offline", 500);
+        }
+        return true;
+    }
+    // ── POST /api/stream/start -- backward-compat explicit RTMP start ────
+    if (method === "POST" && pathname === "/api/stream/start") {
+        try {
+            const bodyStr = await readRequestBody(req);
+            const body = typeof bodyStr === "string" ? JSON.parse(bodyStr) : bodyStr;
+            const rtmpUrl = body?.rtmpUrl;
+            const rtmpKey = body?.rtmpKey;
+            if (!rtmpUrl || !rtmpKey) {
+                error(res, "rtmpUrl and rtmpKey are required", 400);
+                return true;
+            }
+            if (!/^rtmps?:\/\//i.test(rtmpUrl)) {
+                error(res, "rtmpUrl must use rtmp:// or rtmps:// scheme", 400);
+                return true;
+            }
+            // Validate FFmpeg parameters to prevent filter expression injection
+            const VALID_INPUT_MODES = ["testsrc", "avfoundation", "pipe"];
+            const inputMode = body?.inputMode ?? "testsrc";
+            if (!VALID_INPUT_MODES.includes(inputMode)) {
+                error(res, `inputMode must be one of: ${VALID_INPUT_MODES.join(", ")}`, 400);
+                return true;
+            }
+            const resolution = body?.resolution || "1280x720";
+            if (!/^\d{3,4}x\d{3,4}$/.test(resolution)) {
+                error(res, "resolution must match WIDTHxHEIGHT (e.g. 1280x720)", 400);
+                return true;
+            }
+            const bitrate = body?.bitrate || "2500k";
+            if (!/^\d+k$/.test(bitrate)) {
+                error(res, "bitrate must match NUMBERk (e.g. 2500k)", 400);
+                return true;
+            }
+            const framerate = body?.framerate ?? 30;
+            if (typeof framerate !== "number" ||
+                !Number.isInteger(framerate) ||
+                framerate < 1 ||
+                framerate > 60) {
+                error(res, "framerate must be an integer between 1 and 60", 400);
+                return true;
+            }
+            await state.streamManager.start({
+                rtmpUrl,
+                rtmpKey,
+                inputMode,
+                resolution,
+                bitrate,
+                framerate,
+            });
+            json(res, { ok: true, message: "Stream started" });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Stream start failed", 500);
+        }
+        return true;
+    }
+    // ── POST /api/stream/stop -- backward-compat explicit stop ───────────
+    if (method === "POST" && pathname === "/api/stream/stop") {
+        try {
+            const result = await state.streamManager.stop();
+            json(res, { ok: true, ...result });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Stream stop failed", 500);
+        }
+        return true;
+    }
+    // ── GET /api/stream/status -- local stream health ────────────────────
+    if (method === "GET" && pathname === "/api/stream/status") {
+        const health = state.streamManager.getHealth();
+        const activeDest = getActiveDestination(state);
+        const destInfo = activeDest
+            ? { id: activeDest.id, name: activeDest.name }
+            : null;
+        json(res, { ok: true, ...health, destination: destInfo });
+        return true;
+    }
+    // ── POST /api/stream/volume -- set stream volume (0-100) ─────────────
+    if (method === "POST" && pathname === "/api/stream/volume") {
+        try {
+            const body = await readRequestBody(req);
+            const parsed = typeof body === "string" ? JSON.parse(body) : body;
+            const level = parsed?.volume;
+            if (typeof level !== "number" ||
+                !Number.isFinite(level) ||
+                level < 0 ||
+                level > 100) {
+                error(res, "volume must be a number between 0 and 100", 400);
+                return true;
+            }
+            await state.streamManager.setVolume(level);
+            json(res, {
+                ok: true,
+                volume: state.streamManager.getVolume(),
+                muted: state.streamManager.isMuted(),
+            });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to set volume", 500);
+        }
+        return true;
+    }
+    // ── POST /api/stream/mute -- mute stream audio ──────────────────────
+    if (method === "POST" && pathname === "/api/stream/mute") {
+        try {
+            await state.streamManager.mute();
+            json(res, {
+                ok: true,
+                muted: true,
+                volume: state.streamManager.getVolume(),
+            });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to mute", 500);
+        }
+        return true;
+    }
+    // ── POST /api/stream/unmute -- unmute stream audio ───────────────────
+    if (method === "POST" && pathname === "/api/stream/unmute") {
+        try {
+            await state.streamManager.unmute();
+            json(res, {
+                ok: true,
+                muted: false,
+                volume: state.streamManager.getVolume(),
+            });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to unmute", 500);
+        }
+        return true;
+    }
+    // ── GET /api/streaming/destinations -- list configured destination ───
+    if (method === "GET" && pathname === "/api/streaming/destinations") {
+        const destinations = Array.from(state.destinations.values()).map((d) => ({
+            id: d.id,
+            name: d.name,
+            active: d.id ===
+                (state.activeDestinationId ?? state.destinations.keys().next().value),
+        }));
+        json(res, { ok: true, destinations });
+        return true;
+    }
+    // ── POST /api/streaming/destination -- set active destination ────────
+    if (method === "POST" && pathname === "/api/streaming/destination") {
+        try {
+            const body = await readRequestBody(req);
+            const parsed = typeof body === "string" ? JSON.parse(body) : body;
+            const destinationId = parsed?.destinationId;
+            if (!destinationId) {
+                error(res, "destinationId is required", 400);
+                return true;
+            }
+            const target = state.destinations.get(destinationId);
+            if (target) {
+                state.activeDestinationId = destinationId;
+                json(res, {
+                    ok: true,
+                    destination: { id: target.id, name: target.name },
+                });
+            }
+            else {
+                error(res, `Unknown destination: ${destinationId}`, 404);
+            }
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to set destination", 500);
+        }
+        return true;
+    }
+    // ── GET /api/stream/overlay-layout -- read overlay config ─────────────
+    // Supports ?destination=<id> for per-destination layouts.
+    if (method === "GET" && pathname === "/api/stream/overlay-layout") {
+        try {
+            const destId = parseDestinationQuery(req.url);
+            const layout = readOverlayLayout(destId, getActiveDestination(state));
+            json(res, { ok: true, layout, destinationId: destId ?? null });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to read overlay layout", 500);
+        }
+        return true;
+    }
+    // ── POST /api/stream/overlay-layout -- save overlay config ────────────
+    // Supports ?destination=<id> for per-destination layouts.
+    if (method === "POST" && pathname === "/api/stream/overlay-layout") {
+        try {
+            const destId = parseDestinationQuery(req.url);
+            const body = await readRequestBody(req);
+            const parsed = typeof body === "string" ? JSON.parse(body) : body;
+            const layout = parsed?.layout;
+            if (!layout || layout.version !== 1 || !Array.isArray(layout.widgets)) {
+                error(res, "Invalid layout: must have { version: 1, widgets: [...] }", 400);
+                return true;
+            }
+            writeOverlayLayout(layout, destId);
+            json(res, { ok: true, layout, destinationId: destId ?? null });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to save overlay layout", 500);
+        }
+        return true;
+    }
+    // ── GET /api/stream/settings -- read stream visual settings ───────────
+    if (method === "GET" && pathname === "/api/stream/settings") {
+        try {
+            const settings = readStreamSettings();
+            json(res, { ok: true, settings });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to read settings", 500);
+        }
+        return true;
+    }
+    // ── POST /api/stream/settings -- save stream visual settings ──────────
+    if (method === "POST" && pathname === "/api/stream/settings") {
+        try {
+            const body = await readRequestBody(req);
+            const parsed = typeof body === "string" ? JSON.parse(body) : body;
+            const result = validateStreamSettings(parsed?.settings);
+            if (result.error || !result.settings) {
+                error(res, result.error ?? "Invalid settings", 400);
+                return true;
+            }
+            // Merge with existing settings so partial updates (e.g. just avatarIndex)
+            // don't wipe other fields (e.g. voice config).
+            const existing = readStreamSettings();
+            const merged = { ...existing, ...result.settings };
+            writeStreamSettings(merged);
+            json(res, { ok: true, settings: merged });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to save settings", 500);
+        }
+        return true;
+    }
+    // ── GET /api/stream/source -- get active stream source ───────────────
+    if (method === "GET" && pathname === "/api/stream/source") {
+        json(res, { source: state.activeStreamSource });
+        return true;
+    }
+    // ── POST /api/stream/source -- set active stream source ──────────────
+    if (method === "POST" && pathname === "/api/stream/source") {
+        try {
+            const body = await readRequestBody(req);
+            const { sourceType, customUrl } = JSON.parse(typeof body === "string" ? body : JSON.stringify(body));
+            if (!["stream-tab", "game", "custom-url"].includes(sourceType)) {
+                error(res, "Invalid sourceType", 400);
+                return true;
+            }
+            if (sourceType === "custom-url" && !customUrl) {
+                error(res, "customUrl required for custom-url source", 400);
+                return true;
+            }
+            if (sourceType === "game" && !customUrl) {
+                error(res, "customUrl required for game source", 400);
+                return true;
+            }
+            // Validate URL scheme to prevent file:// or javascript: URI injection.
+            // Only http/https are permitted as capture targets.
+            if ((sourceType === "game" || sourceType === "custom-url") &&
+                customUrl &&
+                !/^https?:\/\//i.test(customUrl)) {
+                error(res, "customUrl must use http:// or https:// scheme", 400);
+                return true;
+            }
+            // Stop current frame capture if active
+            if (state.screenCapture?.isFrameCaptureActive()) {
+                state.screenCapture.stopFrameCapture?.();
+            }
+            // Build capture options
+            const captureOpts = {
+                fps: 15,
+                quality: 70,
+                endpoint: "/api/stream/frame",
+            };
+            if (sourceType === "game" || sourceType === "custom-url") {
+                captureOpts.gameUrl = customUrl;
+            }
+            // Update state
+            state.activeStreamSource = { type: sourceType, url: customUrl };
+            // Restart frame capture if stream is running
+            if (state.streamManager.isRunning() && state.screenCapture) {
+                try {
+                    await state.screenCapture.startFrameCapture(captureOpts);
+                }
+                catch (err) {
+                    logger.warn(`[stream] Failed to restart frame capture after source switch: ${err}`);
+                }
+            }
+            json(res, { ok: true, source: state.activeStreamSource });
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to switch source", 500);
+        }
+        return true;
+    }
+    // ── Voice routes (GET/POST /api/stream/voice*) — delegated ──────────
+    if (pathname.startsWith("/api/stream/voice")) {
+        return handleAutonomousStreamVoiceRoute({
+            req,
+            res,
+            pathname,
+            method,
+            state,
+            getTtsProviderStatus: getRouteTtsProviderStatus,
+            resolveTtsConfig: resolveRouteTtsConfig,
+            ttsStreamBridge: ttsBridgeAdapter,
+            sanitizeSpeechText,
+            readStreamSettings: readRouteStreamSettings,
+            writeStreamSettings: writeRouteStreamSettings,
+        });
+    }
+    return false;
+}
+export async function onAgentMessage(text, state) {
+    return onAutonomousAgentMessage(text, state, {
+        sanitizeSpeechText,
+        readStreamSettings: readRouteStreamSettings,
+        resolveTtsConfig: resolveRouteTtsConfig,
+        ttsStreamBridge: ttsBridgeAdapter,
+    });
+}