@elizaos/agent 0.25.8 → 2.0.0-alpha.83

package/packages/agent/src/api/signal-routes.d.ts

@@ -0,0 +1,39 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { SignalPairingEvent } from "../services/signal-pairing";
+export type SignalPairingEventLike = SignalPairingEvent;
+export interface SignalPairingSessionLike {
+    start(): Promise<void>;
+    stop(): void;
+    getStatus(): string;
+}
+export interface SignalRouteState {
+    signalPairingSessions: Map<string, SignalPairingSessionLike>;
+    broadcastWs?: (data: Record<string, unknown>) => void;
+    config: {
+        connectors?: Record<string, unknown>;
+    };
+    runtime?: {
+        getService(type: string): unknown | null;
+    };
+    saveConfig: () => void;
+    workspaceDir: string;
+}
+export interface SignalRouteDeps {
+    sanitizeAccountId: (accountId: string) => string;
+    signalAuthExists: (workspaceDir: string, accountId: string) => boolean;
+    signalLogout: (workspaceDir: string, accountId: string) => void;
+    createSignalPairingSession: (options: {
+        authDir: string;
+        accountId: string;
+        onEvent: (event: SignalPairingEventLike) => void;
+    }) => SignalPairingSessionLike;
+}
+export declare const MAX_PAIRING_SESSIONS = 10;
+export declare function handleSignalRoute(req: IncomingMessage, res: ServerResponse, pathname: string, method: string, state: SignalRouteState, deps: SignalRouteDeps): Promise<boolean>;
+export declare function applySignalQrOverride(plugins: {
+    id: string;
+    validationErrors: unknown[];
+    configured: boolean;
+    qrConnected?: boolean;
+}[], workspaceDir: string, signalAuthExists: (workspaceDir: string, accountId: string) => boolean): void;
+//# sourceMappingURL=signal-routes.d.ts.map

package/packages/agent/src/api/signal-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-routes.d.ts","sourceRoot":"","sources":["../../../../../src/api/signal-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAExD,MAAM,WAAW,wBAAwB;IACvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,IAAI,CAAC;IACb,SAAS,IAAI,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAC7D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACtD,MAAM,EAAE;QACN,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,CAAC;IACF,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;KAC1C,CAAC;IACF,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,gBAAgB,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACvE,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE,0BAA0B,EAAE,CAAC,OAAO,EAAE;QACpC,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;KAClD,KAAK,wBAAwB,CAAC;CAChC;AAGD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAavC,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,OAAO,CAAC,CAoLlB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE;IACP,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,OAAO,EAAE,CAAC;IAC5B,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,EAAE,EACH,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,GACrE,IAAI,CAaN"}

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

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { readJsonBody as parseJsonBody, sendJson } from "./http-helpers";
+const MAX_BODY_BYTES = 1_048_576;
+export const MAX_PAIRING_SESSIONS = 10;
+async function readJsonBody(req, res) {
+    return parseJsonBody(req, res, { maxBytes: MAX_BODY_BYTES });
+}
+function json(res, data, status = 200) {
+    sendJson(res, data, status);
+}
+export async function handleSignalRoute(req, res, pathname, method, state, deps) {
+    if (!pathname.startsWith("/api/signal"))
+        return false;
+    if (method === "POST" && pathname === "/api/signal/pair") {
+        const body = await readJsonBody(req, res);
+        let accountId;
+        try {
+            accountId = deps.sanitizeAccountId(body && typeof body.accountId === "string" && body.accountId.trim()
+                ? body.accountId.trim()
+                : "default");
+        }
+        catch (err) {
+            json(res, { error: err.message }, 400);
+            return true;
+        }
+        const isReplacing = state.signalPairingSessions.has(accountId);
+        if (!isReplacing &&
+            state.signalPairingSessions.size >= MAX_PAIRING_SESSIONS) {
+            json(res, {
+                error: `Too many concurrent pairing sessions (max ${MAX_PAIRING_SESSIONS})`,
+            }, 429);
+            return true;
+        }
+        const authDir = path.join(state.workspaceDir, "signal-auth", accountId);
+        state.signalPairingSessions.get(accountId)?.stop();
+        const session = deps.createSignalPairingSession({
+            authDir,
+            accountId,
+            onEvent: (event) => {
+                state.broadcastWs?.(event);
+                if (event.status === "connected") {
+                    if (!state.config.connectors)
+                        state.config.connectors = {};
+                    state.config.connectors.signal = {
+                        ...(state.config.connectors.signal ?? {}),
+                        authDir,
+                        enabled: true,
+                    };
+                    try {
+                        state.saveConfig();
+                    }
+                    catch {
+                        /* test envs */
+                    }
+                }
+            },
+        });
+        state.signalPairingSessions.set(accountId, session);
+        void session.start().catch((err) => {
+            console.error(`[signal] Pairing session failed for ${accountId}:`, err instanceof Error ? err.message : String(err));
+            state.signalPairingSessions.delete(accountId);
+        });
+        json(res, { ok: true, accountId, status: session.getStatus() });
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/signal/status") {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        let accountId;
+        try {
+            accountId = deps.sanitizeAccountId(url.searchParams.get("accountId") || "default");
+        }
+        catch (err) {
+            json(res, { error: err.message }, 400);
+            return true;
+        }
+        const session = state.signalPairingSessions.get(accountId);
+        let serviceConnected = false;
+        if (state.runtime) {
+            try {
+                const sigService = state.runtime.getService("signal");
+                if (sigService) {
+                    serviceConnected = Boolean(sigService.connected);
+                }
+            }
+            catch {
+                /* service not yet registered */
+            }
+        }
+        json(res, {
+            accountId,
+            status: session?.getStatus() ?? "idle",
+            authExists: deps.signalAuthExists(state.workspaceDir, accountId),
+            serviceConnected,
+        });
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/signal/pair/stop") {
+        const body = await readJsonBody(req, res);
+        let accountId;
+        try {
+            accountId = deps.sanitizeAccountId(body && typeof body.accountId === "string" && body.accountId.trim()
+                ? body.accountId.trim()
+                : "default");
+        }
+        catch (err) {
+            json(res, { error: err.message }, 400);
+            return true;
+        }
+        const session = state.signalPairingSessions.get(accountId);
+        if (session) {
+            session.stop();
+            state.signalPairingSessions.delete(accountId);
+        }
+        json(res, { ok: true, accountId, status: "idle" });
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/signal/disconnect") {
+        const body = await readJsonBody(req, res);
+        let accountId;
+        try {
+            accountId = deps.sanitizeAccountId(body && typeof body.accountId === "string" && body.accountId.trim()
+                ? body.accountId.trim()
+                : "default");
+        }
+        catch (err) {
+            json(res, { error: err.message }, 400);
+            return true;
+        }
+        const session = state.signalPairingSessions.get(accountId);
+        if (session) {
+            session.stop();
+            state.signalPairingSessions.delete(accountId);
+        }
+        try {
+            deps.signalLogout(state.workspaceDir, accountId);
+        }
+        catch (err) {
+            console.warn(`[signal] Logout failed for ${accountId}:`, err instanceof Error ? err.message : String(err));
+        }
+        if (state.config.connectors) {
+            delete state.config.connectors.signal;
+            try {
+                state.saveConfig();
+            }
+            catch {
+                /* test envs */
+            }
+        }
+        json(res, { ok: true, accountId });
+        return true;
+    }
+    return false;
+}
+export function applySignalQrOverride(plugins, workspaceDir, signalAuthExists) {
+    try {
+        if (signalAuthExists(workspaceDir, "default")) {
+            const sigPlugin = plugins.find((plugin) => plugin.id === "signal");
+            if (sigPlugin) {
+                sigPlugin.validationErrors = [];
+                sigPlugin.configured = true;
+                sigPlugin.qrConnected = true;
+            }
+        }
+    }
+    catch {
+        /* workspace dir may not exist */
+    }
+}

package/packages/agent/src/api/stream-persistence.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Stream persistence layer — overlay layout and visual/voice settings I/O.
+ *
+ * Extracted from stream-routes.ts to keep that file focused on route handling.
+ * All functions here deal with reading/writing JSON files under the
+ * `data/stream/` directory.
+ *
+ * @module api/stream-persistence
+ */
+import type { StreamingDestination } from "./streaming-types";
+export interface StreamVoiceSettings {
+    enabled: boolean;
+    provider?: string;
+    autoSpeak?: boolean;
+}
+export interface StreamVisualSettings {
+    theme?: string;
+    avatarIndex?: number;
+    voice?: StreamVoiceSettings;
+}
+/** Sanitize destination ID for use as a filename segment. */
+export declare function safeDestId(id: string): string;
+/** Extract `?destination=<id>` from the raw request URL. */
+export declare function parseDestinationQuery(url?: string): string | undefined;
+/**
+ * Read overlay layout for a destination.
+ * Falls back: destination-specific -> global -> plugin default -> null.
+ */
+export declare function readOverlayLayout(destinationId?: string | null, destination?: StreamingDestination): unknown;
+/** Write overlay layout (to destination-specific or global file). */
+export declare function writeOverlayLayout(layout: unknown, destinationId?: string | null): void;
+/**
+ * Seed the plugin's default overlay layout on first stream start.
+ * Only writes if no destination-specific layout file exists yet.
+ */
+export declare function seedOverlayDefaults(destination: StreamingDestination): void;
+/**
+ * Validate and sanitize a raw settings object into a safe StreamVisualSettings.
+ * Only allows known keys with expected types — rejects everything else.
+ * Returns null with an error message if validation fails.
+ */
+export declare function validateStreamSettings(raw: unknown): {
+    settings: StreamVisualSettings;
+    error?: undefined;
+} | {
+    settings?: undefined;
+    error: string;
+};
+export declare function readStreamSettings(): StreamVisualSettings;
+export declare function writeStreamSettings(settings: StreamVisualSettings): void;
+/**
+ * Build the visual config for browser-capture by merging:
+ *   1. Server-side stream-settings.json (authoritative)
+ *   2. Environment variables (STREAM_THEME, STREAM_AVATAR_INDEX) as fallback
+ *
+ * Reads the active destination's overlay layout when available.
+ */
+export declare function getHeadlessCaptureConfig(destinationId?: string | null): {
+    overlayLayout?: string;
+    theme?: string;
+    avatarIndex?: number;
+    destinationId?: string;
+};
+//# sourceMappingURL=stream-persistence.d.ts.map

package/packages/agent/src/api/stream-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-persistence.d.ts","sourceRoot":"","sources":["../../../../../src/api/stream-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAM9D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B;AAiBD,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C;AAaD,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQtE;AA0BD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,EAC7B,WAAW,CAAC,EAAE,oBAAoB,GACjC,OAAO,CA4BT;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,EACf,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,oBAAoB,GAAG,IAAI,CAM3E;AAQD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,GAEV;IAAE,QAAQ,EAAE,oBAAoB,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAgF1C;AAED,wBAAgB,kBAAkB,IAAI,oBAAoB,CASzD;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAIxE;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAYA"}

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

@@ -0,0 +1,231 @@
+/**
+ * Stream persistence layer — overlay layout and visual/voice settings I/O.
+ *
+ * Extracted from stream-routes.ts to keep that file focused on route handling.
+ * All functions here deal with reading/writing JSON files under the
+ * `data/stream/` directory.
+ *
+ * @module api/stream-persistence
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "@elizaos/core";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const OVERLAY_DIR = path.join(process.env.ELIZA_DATA_DIR || path.join(process.cwd(), "data"), "stream");
+const SETTINGS_FILE = path.join(OVERLAY_DIR, "stream-settings.json");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Sanitize destination ID for use as a filename segment. */
+export function safeDestId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, "");
+}
+/** Return the layout file path for a given destination (or global default). */
+function overlayFileForDestination(destinationId) {
+    if (destinationId) {
+        return path.join(OVERLAY_DIR, `overlay-layout-${safeDestId(destinationId)}.json`);
+    }
+    return path.join(OVERLAY_DIR, "overlay-layout.json");
+}
+/** Extract `?destination=<id>` from the raw request URL. */
+export function parseDestinationQuery(url) {
+    if (!url)
+        return undefined;
+    try {
+        const u = new URL(url, "http://localhost");
+        return u.searchParams.get("destination") || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Overlay layout persistence (per-destination JSON files)
+// ---------------------------------------------------------------------------
+/** Read overlay layout as JSON string for seeding into headless browser. */
+function getOverlayLayoutJson(destinationId) {
+    const files = destinationId
+        ? [
+            overlayFileForDestination(destinationId),
+            overlayFileForDestination(null),
+        ]
+        : [overlayFileForDestination(null)];
+    for (const f of files) {
+        try {
+            if (fs.existsSync(f)) {
+                return fs.readFileSync(f, "utf-8");
+            }
+        }
+        catch {
+            // Not available
+        }
+    }
+    return null;
+}
+/**
+ * Read overlay layout for a destination.
+ * Falls back: destination-specific -> global -> plugin default -> null.
+ */
+export function readOverlayLayout(destinationId, destination) {
+    if (destinationId) {
+        const destFile = overlayFileForDestination(destinationId);
+        try {
+            if (fs.existsSync(destFile)) {
+                return JSON.parse(fs.readFileSync(destFile, "utf-8"));
+            }
+        }
+        catch {
+            logger.warn(`[stream] Failed to read overlay layout for ${destinationId}`);
+        }
+    }
+    const globalFile = overlayFileForDestination(null);
+    try {
+        if (fs.existsSync(globalFile)) {
+            return JSON.parse(fs.readFileSync(globalFile, "utf-8"));
+        }
+    }
+    catch {
+        logger.warn("[stream] Failed to read global overlay layout file");
+    }
+    if (destination?.defaultOverlayLayout) {
+        return destination.defaultOverlayLayout;
+    }
+    return null;
+}
+/** Write overlay layout (to destination-specific or global file). */
+export function writeOverlayLayout(layout, destinationId) {
+    fs.mkdirSync(OVERLAY_DIR, { recursive: true });
+    const file = overlayFileForDestination(destinationId);
+    fs.writeFileSync(file, JSON.stringify(layout, null, 2), "utf-8");
+    const label = destinationId ? `[${destinationId}]` : "[global]";
+    logger.info(`[stream] Overlay layout ${label} saved`);
+}
+/**
+ * Seed the plugin's default overlay layout on first stream start.
+ * Only writes if no destination-specific layout file exists yet.
+ */
+export function seedOverlayDefaults(destination) {
+    if (!destination.defaultOverlayLayout)
+        return;
+    const destFile = overlayFileForDestination(destination.id);
+    if (fs.existsSync(destFile))
+        return;
+    writeOverlayLayout(destination.defaultOverlayLayout, destination.id);
+    logger.info(`[stream] Seeded default overlay layout for ${destination.name}`);
+}
+// ---------------------------------------------------------------------------
+// Stream visual/voice settings persistence
+// ---------------------------------------------------------------------------
+const SETTINGS_MAX_JSON_BYTES = 4096;
+/**
+ * Validate and sanitize a raw settings object into a safe StreamVisualSettings.
+ * Only allows known keys with expected types — rejects everything else.
+ * Returns null with an error message if validation fails.
+ */
+export function validateStreamSettings(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { error: "Settings must be a non-array object" };
+    }
+    // Reject if serialized payload is too large
+    const serialized = JSON.stringify(raw);
+    if (serialized.length > SETTINGS_MAX_JSON_BYTES) {
+        return {
+            error: `Settings payload exceeds ${SETTINGS_MAX_JSON_BYTES} byte limit`,
+        };
+    }
+    const input = raw;
+    const result = {};
+    // theme: optional string, max 64 chars
+    if ("theme" in input) {
+        if (typeof input.theme !== "string" || input.theme.length > 64) {
+            return { error: "theme must be a string (max 64 chars)" };
+        }
+        result.theme = input.theme;
+    }
+    // avatarIndex: optional non-negative integer
+    if ("avatarIndex" in input) {
+        if (typeof input.avatarIndex !== "number" ||
+            !Number.isInteger(input.avatarIndex) ||
+            input.avatarIndex < 0 ||
+            input.avatarIndex > 999) {
+            return { error: "avatarIndex must be an integer between 0 and 999" };
+        }
+        result.avatarIndex = input.avatarIndex;
+    }
+    // voice: optional object with known fields
+    if ("voice" in input) {
+        if (!input.voice ||
+            typeof input.voice !== "object" ||
+            Array.isArray(input.voice)) {
+            return { error: "voice must be an object" };
+        }
+        const v = input.voice;
+        const voice = {
+            enabled: false,
+        };
+        if ("enabled" in v) {
+            if (typeof v.enabled !== "boolean") {
+                return { error: "voice.enabled must be a boolean" };
+            }
+            voice.enabled = v.enabled;
+        }
+        if ("autoSpeak" in v) {
+            if (typeof v.autoSpeak !== "boolean") {
+                return { error: "voice.autoSpeak must be a boolean" };
+            }
+            voice.autoSpeak = v.autoSpeak;
+        }
+        if ("provider" in v) {
+            if (typeof v.provider !== "string" || v.provider.length > 64) {
+                return { error: "voice.provider must be a string (max 64 chars)" };
+            }
+            voice.provider = v.provider;
+        }
+        result.voice = voice;
+    }
+    // Reject unknown top-level keys
+    const knownKeys = new Set(["theme", "avatarIndex", "voice"]);
+    for (const key of Object.keys(input)) {
+        if (!knownKeys.has(key)) {
+            return { error: `Unknown settings key: ${key}` };
+        }
+    }
+    return { settings: result };
+}
+export function readStreamSettings() {
+    try {
+        if (fs.existsSync(SETTINGS_FILE)) {
+            return JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf-8"));
+        }
+    }
+    catch {
+        logger.warn("[stream] Failed to read stream settings file");
+    }
+    return {};
+}
+export function writeStreamSettings(settings) {
+    fs.mkdirSync(OVERLAY_DIR, { recursive: true });
+    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), "utf-8");
+    logger.info("[stream] Stream settings saved");
+}
+/**
+ * Build the visual config for browser-capture by merging:
+ *   1. Server-side stream-settings.json (authoritative)
+ *   2. Environment variables (STREAM_THEME, STREAM_AVATAR_INDEX) as fallback
+ *
+ * Reads the active destination's overlay layout when available.
+ */
+export function getHeadlessCaptureConfig(destinationId) {
+    const settings = readStreamSettings();
+    return {
+        overlayLayout: getOverlayLayoutJson(destinationId) ?? undefined,
+        theme: settings.theme ?? process.env.STREAM_THEME,
+        avatarIndex: settings.avatarIndex ??
+            (process.env.STREAM_AVATAR_INDEX
+                ? parseInt(process.env.STREAM_AVATAR_INDEX, 10)
+                : undefined),
+        destinationId: destinationId ?? undefined,
+    };
+}

package/packages/agent/src/api/stream-route-state.d.ts

@@ -0,0 +1,50 @@
+import type { StreamingDestination } from "./streaming-types";
+export interface StreamRouteState {
+    streamManager: {
+        isRunning(): boolean;
+        writeFrame(buf: Buffer): boolean;
+        start(config: unknown): Promise<void>;
+        stop(): Promise<{
+            uptime: number;
+        }>;
+        getHealth(): {
+            running: boolean;
+            ffmpegAlive: boolean;
+            uptime: number;
+            frameCount: number;
+            volume: number;
+            muted: boolean;
+            audioSource: string;
+            inputMode: string | null;
+        };
+        getVolume(): number;
+        isMuted(): boolean;
+        setVolume(level: number): Promise<void>;
+        mute(): Promise<void>;
+        unmute(): Promise<void>;
+    };
+    port?: number;
+    captureUrl?: string;
+    screenCapture?: {
+        isFrameCaptureActive(): boolean;
+        startFrameCapture(opts: {
+            fps?: number;
+            quality?: number;
+            endpoint?: string;
+            gameUrl?: string;
+        }): Promise<void>;
+        stopFrameCapture?(): void;
+    };
+    destinations: Map<string, StreamingDestination>;
+    activeDestinationId?: string;
+    activeStreamSource: {
+        type: "stream-tab" | "game" | "custom-url";
+        url?: string;
+    };
+    config?: {
+        messages?: {
+            tts?: Record<string, unknown>;
+        };
+    };
+}
+//# sourceMappingURL=stream-route-state.d.ts.map

package/packages/agent/src/api/stream-route-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-route-state.d.ts","sourceRoot":"","sources":["../../../../../src/api/stream-route-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE;QACb,SAAS,IAAI,OAAO,CAAC;QACrB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QACjC,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,IAAI,OAAO,CAAC;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpC,SAAS,IAAI;YACX,OAAO,EAAE,OAAO,CAAC;YACjB,WAAW,EAAE,OAAO,CAAC;YACrB,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;YACnB,MAAM,EAAE,MAAM,CAAC;YACf,KAAK,EAAE,OAAO,CAAC;YACf,WAAW,EAAE,MAAM,CAAC;YACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;SAC1B,CAAC;QACF,SAAS,IAAI,MAAM,CAAC;QACpB,OAAO,IAAI,OAAO,CAAC;QACnB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KACzB,CAAC;IACF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE;QACd,oBAAoB,IAAI,OAAO,CAAC;QAChC,iBAAiB,CAAC,IAAI,EAAE;YACtB,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAClB,gBAAgB,CAAC,IAAI,IAAI,CAAC;KAC3B,CAAC;IACF,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAChD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE;QAClB,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,YAAY,CAAC;QAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE;YACT,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAC/B,CAAC;KACH,CAAC;CACH"}

package/packages/agent/src/api/stream-route-state.js

@@ -0,0 +1 @@
+export {};

package/packages/agent/src/api/stream-routes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { IncomingMessage, ServerResponse } from "node:http";
+import type { StreamConfig } from "../services/stream-manager";
+import type { StreamRouteState } from "./stream-route-state";
+import type { StreamingDestination } from "./streaming-types";
+export type { StreamRouteState } from "./stream-route-state";
+/**
+ * A streaming destination provides RTMP credentials and optional lifecycle
+ * hooks. Canonical definition lives in plugin-streaming-base; re-exported here
+ * so existing consumers keep working.
+ */
+export type { OverlayLayoutData, StreamingDestination, } from "./streaming-types";
+/** Resolve the active streaming destination from the registry. */
+export declare function getActiveDestination(state: StreamRouteState): StreamingDestination | undefined;
+/**
+ * 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 declare function detectCaptureMode(): StreamConfig["inputMode"];
+/**
+ * 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 declare function ensureXvfb(display: string, resolution: string): Promise<boolean>;
+/** Returns `true` if handled, `false` to fall through. */
+export declare function handleStreamRoute(req: IncomingMessage, res: ServerResponse, pathname: string, method: string, state: StreamRouteState): Promise<boolean>;
+export declare function onAgentMessage(text: string, state: StreamRouteState): Promise<void>;
+//# sourceMappingURL=stream-routes.d.ts.map

package/packages/agent/src/api/stream-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-routes.d.ts","sourceRoot":"","sources":["../../../../../src/api/stream-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAuB/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAK7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAwC7D;;;;GAIG;AACH,YAAY,EACV,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAE3B,kEAAkE;AAClE,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gBAAgB,GACtB,oBAAoB,GAAG,SAAS,CAOlC;AAmED;;;;;;;;;GASG;AACH,sCAAsC;AACtC,wBAAgB,iBAAiB,IAAI,YAAY,CAAC,WAAW,CAAC,CAqB7D;AAMD;;;GAGG;AACH,sCAAsC;AACtC,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAuDlB;AAkOD,0DAA0D;AAC1D,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,OAAO,CAAC,CAwhBlB;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAOf"}