@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/meetings/capture-orchestrator.js

@@ -0,0 +1,531 @@
+// CAPTURE ORCHESTRATION (daemon) — manages a meeting capture session: spawns the
+// native `meetcap` helper, and on stop runs the engine (diarize + speaker-ID + ASR)
+// to produce a Meeting in the ingested store the daemon already serves via
+// /api/meetings. The native helper + engine are PLUGGABLE — env-configured commands
+// by default, or injected for tests — so the daemon carries no hard dependency on the
+// Swift/Python prototypes. Design: docs/research/macos-meeting-recorder-engine/DESKTOP-CAPTURE-INTEGRATION.md
+import os from "node:os";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import pino from "pino";
+import { execCommand, spawnProcess } from "../../utils/spawn.js";
+import { createLiveTranscription as createLiveTranscriptionSeam, } from "./live-transcription.js";
+import { ensureLocalSpeechModels, getLocalSpeechModelDir, } from "../speech/providers/local/models.js";
+import { DEFAULT_LOCAL_STT_MODEL } from "../speech/providers/local/sherpa/model-catalog.js";
+import { SherpaOfflineRecognizerEngine } from "../speech/providers/local/sherpa/sherpa-offline-recognizer.js";
+import { getCaptureStreamWs } from "./capture-stream-ws.js";
+import { appendIngestedMeeting, deriveStatus, ensureWorkdir, } from "./meetings-http.js";
+/**
+ * The meetcap helper MUST run as its own TCC "responsible process" or macOS feeds its
+ * system-audio tap silent (zero-filled) buffers — see the deep root-cause in
+ * docs/research. A child spawned directly by this daemon is attributed to the daemon
+ * (Electron), which lacks the System-Audio-Recording grant. Launching the .app via
+ * LaunchServices (`open`) starts it in its own process tree, so ITS grant applies.
+ *
+ * Returns the .app bundle path if MEETCAP_BIN points inside one (…/X.app/Contents/MacOS/bin),
+ * else null (bare binary on PATH → no responsible-process fix available, direct spawn).
+ */
+export function meetcapAppBundle(binPath) {
+    const marker = ".app/Contents/MacOS/";
+    const i = binPath.indexOf(marker);
+    return i > 0 ? binPath.slice(0, i + ".app".length) : null;
+}
+/**
+ * Parse `meetcap list` stdout into capturable apps. Lines look like:
+ *   "  pid 84347    Slack"
+ * Rows whose name column is just the pid echoed back ("pid 84347") are unnamed
+ * helper processes — dropped. Result is de-duplicated by name, first pid wins.
+ */
+// macOS system/audio-plumbing processes that show up as "audio-active" but are never
+// a meeting the user wants to capture. Dropped from the picker (Whole-system-audio still
+// captures everything regardless).
+const SYSTEM_APP_DENYLIST = new Set([
+    "Control Center",
+    "universalaccessd",
+    "PowerChime",
+    "DisplayLink Manager",
+    "loginwindow",
+    "SimAudioProcessorService",
+    "WebThumbnailExtension Graphics and Media",
+    "coreaudiod",
+    "krisp",
+]);
+export function parseAppList(stdout) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of stdout.split("\n")) {
+        const m = /^\s*pid\s+(\d+)\s+(.*\S)\s*$/.exec(raw);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const name = m[2].trim();
+        if (!name || name === `pid ${pid}` || seen.has(name))
+            continue;
+        if (SYSTEM_APP_DENYLIST.has(name) || /\bHelper\b|\(Plugin\)/.test(name))
+            continue;
+        seen.add(name);
+        out.push({ pid, name });
+    }
+    return out;
+}
+const MEETCAP_BIN = process.env.MEETCAP_BIN ?? "meetcap";
+// Optional engine command: `<cmd> <far> <near> <workdir>` → stdout JSON {participants,transcript}.
+// Unset ⇒ the recording is stored with no transcript yet (engine wired separately).
+const ENGINE_CMD = process.env.MEETINGS_ENGINE_CMD ?? "";
+const engineLogger = pino({ level: process.env.PASEO_LOG_LEVEL ?? "info" }).child({
+    module: "meetings",
+    component: "capture-orchestrator",
+});
+// Same precedence as the meeting engine's resolver: env override -> PASEO_HOME.
+function resolveModelsDir() {
+    const paseoHome = process.env.PASEO_HOME ?? path.join(os.homedir(), ".paseo");
+    return process.env.PASEO_LOCAL_MODELS_DIR ?? path.join(paseoHome, "models", "local-speech");
+}
+// The realtime seam decodes against a shared offline recognizer. Building it (large models +
+// native init) is expensive, so memoize a single promise for the daemon process. Never resolved
+// in a unit test - tests inject `deps.createLiveTranscription` and this path is never taken.
+let sharedRealtimeEnginePromise = null;
+async function buildRealtimeEngine() {
+    const modelsDir = resolveModelsDir();
+    await ensureLocalSpeechModels({
+        modelsDir,
+        modelIds: [DEFAULT_LOCAL_STT_MODEL],
+        logger: engineLogger,
+    }); // idempotent; downloads once
+    const modelDir = getLocalSpeechModelDir(modelsDir, DEFAULT_LOCAL_STT_MODEL);
+    return new SherpaOfflineRecognizerEngine({
+        model: {
+            kind: "nemo_transducer",
+            encoder: `${modelDir}/encoder.int8.onnx`,
+            decoder: `${modelDir}/decoder.int8.onnx`,
+            joiner: `${modelDir}/joiner.int8.onnx`,
+            tokens: `${modelDir}/tokens.txt`,
+        },
+        numThreads: 2,
+        debug: 0,
+    }, engineLogger);
+}
+function getSharedRealtimeEngine() {
+    sharedRealtimeEnginePromise ?? (sharedRealtimeEnginePromise = buildRealtimeEngine());
+    return sharedRealtimeEnginePromise;
+}
+// Watchdog: a recording is owned by the app that started it. The app heartbeats while
+// recording; if it stops (crash / window closed), the daemon auto-stops so meetcap can't
+// record headless forever (a 2h45m runaway happened on 2026-07-01 after a renderer crash).
+const HEARTBEAT_TIMEOUT_MS = 30000; // no ping for 30s → app gone → auto-stop
+const HEARTBEAT_CHECK_MS = 10000;
+const MAX_CAPTURE_MS = 3 * 60 * 60 * 1000; // hard ceiling regardless of heartbeats
+// Silence auto-stop: if the far track (the meeting audio) stays quiet for this long, the
+// meeting is over / on hold → auto-stop so a forgotten recording doesn't run on empty.
+// Configurable via MEETINGS_SILENCE_STOP_MIN (0 disables).
+const SILENCE_STOP_MS = (Number(process.env.MEETINGS_SILENCE_STOP_MIN) || 5) * 60000;
+const SILENCE_CHECK_MS = 45000;
+const SILENCE_WINDOW_S = 50; // analyze the last ~50s of far.caf each check
+const SILENCE_DB = -55; // max_volume above this = real audio present
+/**
+ * Build the meetcap capture argv. With no app selected (null/empty), capture the whole-system
+ * audio mix via `--system` — a meeting is captured regardless of which app owns the audio,
+ * with no per-app picker or PID hunt. A non-empty app routes to `--app <name>` (single-app
+ * capture). This is the deterministic, unit-testable seam for the default-capture decision.
+ */
+export function buildCaptureArgs(app) {
+    return app ? ["capture", "--app", app] : ["capture", "--system"];
+}
+/**
+ * Mode-aware meetcap argv. Extends `buildCaptureArgs` with `--emit pcm` ONLY in live mode: it
+ * streams f32le PCM on stdout for the realtime seam WHILE STILL writing far/near .caf (so the
+ * Stop-time batch finalize is unaffected). batch mode emits no `--emit`. Exported so the argv
+ * contract (live has `--emit pcm`, batch does not) is directly assertable.
+ */
+export function buildCaptureArgv(opts) {
+    const { app, mode } = opts;
+    return [...buildCaptureArgs(app), ...(mode === "live" ? ["--emit", "pcm"] : [])];
+}
+const defaultDeps = {
+    spawnCapture: ({ app, cwd, mode }) => {
+        const bundle = meetcapAppBundle(MEETCAP_BIN);
+        const captureArgs = buildCaptureArgv({ app, mode });
+        if (bundle) {
+            // Launch via LaunchServices so meetcap is its own responsible process (TCC). The
+            // returned child is the short-lived `open`; the capture is stopped via stopCapture.
+            return spawnProcess("open", [
+                "-a",
+                bundle,
+                "--stdout",
+                path.join(cwd, "meetcap.log"),
+                "--env",
+                `MEETCAP_OUTDIR=${cwd}`,
+                "--args",
+                ...captureArgs,
+            ], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        }
+        // Bare binary on PATH — no bundle to launch via `open`; direct spawn (no TCC fix).
+        return spawnProcess(MEETCAP_BIN, captureArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    },
+    stopCapture: async (session) => {
+        // meetcap writes far/near on SIGINT. When launched via `open` the daemon has no direct
+        // handle, so find the running helper by its binary path and signal it, then give it a
+        // moment to flush the .caf files before the engine reads them.
+        const bundle = meetcapAppBundle(MEETCAP_BIN);
+        if (!bundle)
+            return; // direct-spawn path is stopped by the orchestrator's child.kill
+        try {
+            const { stdout } = await execCommand("pgrep", ["-f", `${bundle}/Contents/MacOS/`], {
+                maxBuffer: 1 << 16,
+            });
+            const pids = stdout
+                .split("\n")
+                .map((s) => Number(s.trim()))
+                .filter((n) => n > 0);
+            for (const pid of pids) {
+                try {
+                    process.kill(pid, "SIGINT");
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }
+        catch {
+            /* pgrep found nothing — helper already exited */
+        }
+        // Wait (≤3s) for far.caf to stop growing / appear, so the engine sees a complete file.
+        await new Promise((r) => setTimeout(r, 1500));
+        void session;
+    },
+    processRecording: async (session) => {
+        if (!ENGINE_CMD)
+            return { participants: [], transcript: [] };
+        // eslint-disable-next-line unicorn/prefer-array-find -- need the whole token list (cmd + args), not just the first
+        const parts = ENGINE_CMD.split(/\s+/).filter(Boolean);
+        const [cmd, ...preArgs] = parts;
+        const { stdout } = await execCommand(cmd, [...preArgs, session.far, session.near, session.workdir], { maxBuffer: 1 << 26 });
+        const lines = stdout.trim().split("\n").filter(Boolean);
+        const line = lines[lines.length - 1] ?? "{}";
+        const parsed = JSON.parse(line);
+        return { participants: parsed.participants ?? [], transcript: parsed.transcript ?? [] };
+    },
+    listApps: async () => {
+        try {
+            const { stdout } = await execCommand(MEETCAP_BIN, ["list"], { maxBuffer: 1 << 20 });
+            return parseAppList(stdout);
+        }
+        catch {
+            return []; // meetcap binary absent / not on PATH → no apps to offer
+        }
+    },
+    createLiveTranscription: async ({ stream, sink }) => {
+        const engine = await getSharedRealtimeEngine();
+        return createLiveTranscriptionSeam({ stream, engine, sink });
+    },
+    appendMeeting: appendIngestedMeeting,
+    broadcast: (frame) => getCaptureStreamWs().broadcast(frame),
+    now: () => new Date(),
+    log: (msg) => console.error(`[capture] ${msg}`),
+};
+/** Assemble the ingested-store Meeting record from a finished session + engine output. */
+export function buildMeeting(session, engine, now) {
+    const participants = engine.participants;
+    const unidentified = participants.filter((p) => !p.identified).length;
+    const openQuestions = participants
+        .filter((p) => !p.identified)
+        .map((p) => ({
+        id: `id-${p.id}`,
+        text: `Identify speaker “${p.voiceLabel || p.displayName}”`,
+        kind: "identify",
+    }));
+    if (participants.length === 0) {
+        openQuestions.push({
+            id: `q-${session.id}-engine`,
+            text: "Recording captured — speaker diarization + transcript pending (engine).",
+            kind: "followup",
+        });
+    }
+    return {
+        id: session.id,
+        title: `Recorded meeting — ${now.toLocaleString()}`,
+        startedAt: session.startedAt,
+        status: deriveStatus(unidentified, engine.transcript.length),
+        source: "captured",
+        participants,
+        transcript: engine.transcript,
+        actionItems: [],
+        decisions: [],
+        openQuestions,
+        stats: {
+            participantCount: participants.length,
+            unidentifiedCount: unidentified,
+            turnCount: engine.transcript.length,
+        },
+    };
+}
+/**
+ * Single in-flight capture session. idle → recording (meetcap spawned) → processing
+ * (engine) → ready (Meeting written) | error. Mirrors the meetings-http store layer.
+ */
+export class CaptureOrchestrator {
+    constructor(deps = {}) {
+        this.session = null;
+        this.child = null;
+        // Live-mode only: the in-flight seam handle, awaited + closed on stop to force the final frame.
+        // The seam is VIEW-ONLY - its partials/finals are broadcast, never persisted (AC 4).
+        this.liveHandlePromise = null;
+        this.lastHeartbeat = 0;
+        this.lastAudioMs = 0;
+        this.watchdog = null;
+        this.maxTimer = null;
+        this.silenceTimer = null;
+        this.deps = { ...defaultDeps, ...deps };
+    }
+    getStatus() {
+        return this.session;
+    }
+    /** The app pings this while recording; a gap → the app crashed/closed → auto-stop. */
+    heartbeat() {
+        this.lastHeartbeat = this.deps.now().getTime();
+    }
+    clearGuards() {
+        if (this.watchdog) {
+            clearInterval(this.watchdog);
+            this.watchdog = null;
+        }
+        if (this.maxTimer) {
+            clearTimeout(this.maxTimer);
+            this.maxTimer = null;
+        }
+        if (this.silenceTimer) {
+            clearInterval(this.silenceTimer);
+            this.silenceTimer = null;
+        }
+    }
+    /** Auto-stop after a prolonged quiet stretch on the far track (meeting ended / on hold). */
+    async checkSilence() {
+        const session = this.session;
+        if (!session || session.state !== "recording" || SILENCE_STOP_MS <= 0)
+            return;
+        let hasAudio = false;
+        try {
+            const { stderr } = await execCommand("ffmpeg", [
+                "-v",
+                "info",
+                "-sseof",
+                `-${SILENCE_WINDOW_S}`,
+                "-i",
+                session.far,
+                "-af",
+                "volumedetect",
+                "-f",
+                "null",
+                "-",
+            ], { maxBuffer: 1 << 20 });
+            const m = /max_volume:\s*(-?\d+(?:\.\d+)?)\s*dB/.exec(stderr);
+            hasAudio = m ? Number(m[1]) > SILENCE_DB : true; // unparseable → assume audio (don't stop)
+        }
+        catch {
+            return; // file mid-write / ffmpeg hiccup → skip this check, never false-stop
+        }
+        const now = this.deps.now().getTime();
+        if (hasAudio) {
+            this.lastAudioMs = now;
+            return;
+        }
+        if (now - this.lastAudioMs > SILENCE_STOP_MS) {
+            this.deps.log(`far track silent for ${Math.round((now - this.lastAudioMs) / 60000)}min — auto-stopping`);
+            void this.stop().catch(() => { });
+        }
+    }
+    startGuards() {
+        this.lastHeartbeat = this.deps.now().getTime();
+        this.lastAudioMs = this.deps.now().getTime();
+        this.clearGuards();
+        this.watchdog = setInterval(() => {
+            if (!this.session || this.session.state !== "recording")
+                return;
+            const idle = this.deps.now().getTime() - this.lastHeartbeat;
+            if (idle > HEARTBEAT_TIMEOUT_MS) {
+                this.deps.log(`no app heartbeat for ${Math.round(idle / 1000)}s — auto-stopping (app crashed/closed)`);
+                void this.stop().catch(() => { });
+            }
+        }, HEARTBEAT_CHECK_MS);
+        this.maxTimer = setTimeout(() => {
+            if (this.session?.state === "recording") {
+                this.deps.log(`max capture duration (${MAX_CAPTURE_MS / 3.6e6}h) reached — auto-stopping`);
+                void this.stop().catch(() => { });
+            }
+        }, MAX_CAPTURE_MS);
+        if (SILENCE_STOP_MS > 0) {
+            this.silenceTimer = setInterval(() => void this.checkSilence(), SILENCE_CHECK_MS);
+            this.silenceTimer.unref?.();
+        }
+        // Don't let the guards keep the process alive on their own.
+        this.watchdog.unref?.();
+        this.maxTimer.unref?.();
+    }
+    /** Capturable audio-active apps (from `meetcap list`) for the UI's picker. */
+    listApps() {
+        return this.deps.listApps();
+    }
+    start(opts = {}) {
+        if (this.session &&
+            (this.session.state === "recording" || this.session.state === "processing")) {
+            throw new Error(`a capture session is already ${this.session.state}`);
+        }
+        // Default preserves the pre-epic behavior: batch mode, unchanged argv, no realtime seam.
+        const mode = opts.mode ?? "batch";
+        const startedAt = this.deps.now().toISOString();
+        const id = `capture-${startedAt.replace(/[:.]/g, "-")}`;
+        const workdir = ensureWorkdir(id);
+        const session = {
+            id,
+            state: "recording",
+            startedAt,
+            app: opts.app ?? null,
+            mode,
+            far: path.join(workdir, "far.caf"),
+            near: path.join(workdir, "near.caf"),
+            workdir,
+            meetingId: null,
+            error: null,
+        };
+        this.session = session;
+        this.liveHandlePromise = null;
+        this.child = this.deps.spawnCapture({ app: session.app, cwd: workdir, mode });
+        // A capture-helper spawn failure (e.g. `meetcap` ENOENT) or a mid-capture crash emits 'error'
+        // on the child. Handle it here so a helper fault degrades THIS session to `error` instead of
+        // bubbling as an uncaught exception that crashes the daemon.
+        this.child.on("error", (err) => this.onCaptureHelperError(session, err));
+        if (mode === "live") {
+            this.startLiveTranscription(session);
+        }
+        this.startGuards();
+        // idle -> recording transition (broadcast to any capture-stream subscriber).
+        this.deps.broadcast({ type: "state", state: "recording" });
+        this.deps.log(`recording ${id} (mode=${mode})${session.app ? ` (app=${session.app})` : ""}`);
+        return session;
+    }
+    // Wire the live child's stdout into the realtime seam. The sink broadcasts every partial/final
+    // over the capture-stream WS (view-only). Kept off the start() critical path (the seam's
+    // connect() is async) so start returns immediately with the recording session.
+    startLiveTranscription(session) {
+        const stdout = this.child?.stdout;
+        if (!stdout) {
+            this.deps.log(`live capture ${session.id}: child exposed no stdout stream`);
+            return;
+        }
+        this.liveHandlePromise = this.deps.createLiveTranscription({
+            stream: stdout,
+            sink: (event) => this.onLiveEvent(event),
+        });
+        this.liveHandlePromise.catch((err) => {
+            this.deps.log(`live transcription failed to start for ${session.id}: ${String(err)}`);
+        });
+    }
+    // A capture-helper (meetcap) spawn/runtime failure must never crash the daemon: degrade the
+    // in-flight session to `error` and drop the child. No-op if the session already moved past
+    // recording (e.g. a late 'error' after stop() began finalizing).
+    onCaptureHelperError(session, err) {
+        this.deps.log(`capture helper failed for ${session.id}: ${err.message}`);
+        this.child = null;
+        if (this.session?.id === session.id && session.state === "recording") {
+            session.error = err.message;
+            this.setState(session, "error");
+        }
+    }
+    // Broadcast every live partial/final frame over the capture-stream WS. VIEW-ONLY: nothing here
+    // is accumulated for persistence - the Python batch engine is the sole writer on stop (AC 4).
+    onLiveEvent(event) {
+        if (event.type === "partial" || event.type === "final") {
+            this.deps.broadcast({
+                type: event.type,
+                segmentId: event.segmentId,
+                text: event.text,
+                atSeconds: event.atSeconds,
+            });
+            return;
+        }
+        // event.type === "error": a degraded live view never corrupts persistence; log and continue.
+        this.deps.log(`live transcription error for ${this.session?.id ?? "?"}: ${event.error.message}`);
+    }
+    async stop() {
+        const session = this.session;
+        if (!session || session.state !== "recording") {
+            throw new Error("no active recording to stop");
+        }
+        this.clearGuards();
+        // Stop the helper. With the `open`/LaunchServices path the daemon has no direct handle,
+        // so stopCapture finds + SIGINTs meetcap; the direct-spawn fallback also gets child.kill.
+        try {
+            await this.deps.stopCapture(session);
+        }
+        catch {
+            /* best-effort */
+        }
+        if (this.child) {
+            try {
+                this.child.kill("SIGINT");
+            }
+            catch {
+                /* already exited */
+            }
+            this.child = null;
+        }
+        // If the app uploaded a real mic recording, use it as the near track — overwriting
+        // meetcap's silent one. The renderer holds Microphone permission via the normal
+        // browser flow; meetcap's open-launched helper structurally cannot (see capture-http).
+        const upload = path.join(session.workdir, "near-upload.webm");
+        if (existsSync(upload)) {
+            try {
+                await execCommand("ffmpeg", ["-y", "-i", upload, "-ac", "1", "-ar", "16000", session.near]);
+                this.deps.log(`near track sourced from app mic upload`);
+            }
+            catch (e) {
+                this.deps.log(`near upload convert failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        this.setState(session, "processing");
+        this.deps.log(`processing ${session.id}`);
+        try {
+            // Live mode: force the realtime final (view-only broadcast) + tear the seam down. The
+            // batch engine below is STILL the sole writer of the persisted transcript (AC 4). Batch
+            // mode leaves this untouched.
+            if (session.mode === "live") {
+                await this.finalizeLiveView(session);
+            }
+            const engine = await this.deps.processRecording(session);
+            const meeting = buildMeeting(session, engine, this.deps.now());
+            this.deps.appendMeeting(meeting);
+            session.meetingId = meeting.id;
+            this.setState(session, "ready");
+            this.deps.log(`ready ${session.id} -> meeting ${meeting.id} (${meeting.stats.participantCount} speakers, ${meeting.stats.turnCount} turns)`);
+        }
+        catch (e) {
+            session.error = e instanceof Error ? e.message : String(e);
+            this.setState(session, "error");
+            this.deps.log(`error ${session.id}: ${session.error}`);
+        }
+        return session;
+    }
+    // Live-mode stop hook: await the in-flight seam handle, then `close()` it to force the realtime
+    // session's final (broadcast as a view-only frame) and tear down both native sessions. Persists
+    // NOTHING - the batch engine in stop() is the sole writer of the transcript (AC 4).
+    async finalizeLiveView(session) {
+        const handle = this.liveHandlePromise ? await this.liveHandlePromise.catch(() => null) : null;
+        if (handle) {
+            await handle.close();
+        }
+        this.liveHandlePromise = null;
+        this.deps.log(`live view finalized ${session.id}`);
+    }
+    // Set + broadcast a state transition in one place so every capture-stream subscriber sees the
+    // idle|recording|processing|ready|error lifecycle (no transition missed).
+    setState(session, state) {
+        session.state = state;
+        this.deps.broadcast({ type: "state", state });
+    }
+}
+let singleton = null;
+export function getCaptureOrchestrator() {
+    singleton ?? (singleton = new CaptureOrchestrator());
+    return singleton;
+}
+//# sourceMappingURL=capture-orchestrator.js.map

package/dist/server/server/meetings/capture-stream-ws.d.ts

@@ -0,0 +1,42 @@
+import type { IncomingMessage } from "node:http";
+import type net from "node:net";
+import type { CaptureState } from "./capture-orchestrator.js";
+/** The URL the capture-stream WS claims. Every other upgrade URL is a no-op (see `upgrade`). */
+export declare const CAPTURE_STREAM_PATH = "/api/meetings/capture/stream";
+/** JSON text frames broadcast to capture-stream clients. Shapes match the AC 2 contract exactly. */
+export type CaptureStreamFrame = {
+    type: "partial";
+    segmentId: string;
+    text: string;
+    atSeconds: number;
+} | {
+    type: "final";
+    segmentId: string;
+    text: string;
+    atSeconds: number;
+} | {
+    type: "state";
+    state: CaptureState;
+};
+/**
+ * Second-path capture-stream WebSocket. Registered on the shared httpServer's `upgrade` event
+ * BEFORE the VoiceAssistant `/ws` server attaches (bootstrap.ts). No-ops on any non-matching URL.
+ */
+export declare class CaptureStreamWs {
+    private readonly wss;
+    private readonly clients;
+    constructor();
+    /**
+     * httpServer `upgrade` listener. Returns early (no-op) unless the URL is the capture-stream
+     * path, so `/ws` and script-proxy upgrades pass through to their own listeners untouched.
+     */
+    readonly upgrade: (req: IncomingMessage, socket: net.Socket, head: Buffer) => void;
+    /** JSON.stringify the frame and send it to every OPEN client. Fire-and-forget. */
+    broadcast(frame: CaptureStreamFrame): void;
+    /** Number of currently-connected clients (used by tests). */
+    clientCount(): number;
+    /** Close every client socket and the underlying server. Idempotent. */
+    close(): void;
+}
+export declare function getCaptureStreamWs(): CaptureStreamWs;
+//# sourceMappingURL=capture-stream-ws.d.ts.map

package/dist/server/server/meetings/capture-stream-ws.js

@@ -0,0 +1,68 @@
+import { WebSocket, WebSocketServer } from "ws";
+/** The URL the capture-stream WS claims. Every other upgrade URL is a no-op (see `upgrade`). */
+export const CAPTURE_STREAM_PATH = "/api/meetings/capture/stream";
+/**
+ * Second-path capture-stream WebSocket. Registered on the shared httpServer's `upgrade` event
+ * BEFORE the VoiceAssistant `/ws` server attaches (bootstrap.ts). No-ops on any non-matching URL.
+ */
+export class CaptureStreamWs {
+    constructor() {
+        this.wss = new WebSocketServer({ noServer: true });
+        this.clients = new Set();
+        /**
+         * httpServer `upgrade` listener. Returns early (no-op) unless the URL is the capture-stream
+         * path, so `/ws` and script-proxy upgrades pass through to their own listeners untouched.
+         */
+        this.upgrade = (req, socket, head) => {
+            if (req.url !== CAPTURE_STREAM_PATH) {
+                return; // not ours - let the other upgrade listeners (script-proxy, /ws) handle it
+            }
+            this.wss.handleUpgrade(req, socket, head, (ws) => {
+                this.wss.emit("connection", ws, req);
+            });
+        };
+        this.wss.on("connection", (ws) => {
+            this.clients.add(ws);
+            const drop = () => this.clients.delete(ws);
+            ws.on("close", drop);
+            ws.on("error", drop);
+        });
+    }
+    /** JSON.stringify the frame and send it to every OPEN client. Fire-and-forget. */
+    broadcast(frame) {
+        if (this.clients.size === 0) {
+            return;
+        }
+        const data = JSON.stringify(frame);
+        for (const ws of this.clients) {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(data);
+            }
+        }
+    }
+    /** Number of currently-connected clients (used by tests). */
+    clientCount() {
+        return this.clients.size;
+    }
+    /** Close every client socket and the underlying server. Idempotent. */
+    close() {
+        for (const ws of this.clients) {
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closing */
+            }
+        }
+        this.clients.clear();
+        this.wss.close();
+    }
+}
+// Daemon-wide singleton so the capture orchestrator (also a singleton) and the bootstrap upgrade
+// registration share one instance. Tests construct `new CaptureStreamWs()` directly and inject it.
+let singleton = null;
+export function getCaptureStreamWs() {
+    singleton ?? (singleton = new CaptureStreamWs());
+    return singleton;
+}
+//# sourceMappingURL=capture-stream-ws.js.map