@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/voice-realtime.js

@@ -0,0 +1,787 @@
+// BFF realtime voice control plane (Issue #497, Epic #491, ADR-0058 D3/D6, ADR-0059). Re-opens the
+// BFF WebSocket upgrade — deliberately hard-rejected for every other path (server.ts) — for the single
+// loopback control path `/api/voice/control`, and ONLY when the resolved voice capability is the
+// full-realtime profile and policy permits it (AC1). The WebSocket carries the #496 control/signaling
+// protocol; raw audio never rides it — real-time media flows browser↔provider over native WebRTC
+// (DTLS-SRTP), negotiated by the preferred proxied-SDP mode so the long-lived provider credential
+// never reaches the browser (AC2).
+//
+// Security posture (ADR-0058 D6): the upgrade reuses the same loopback `isAllowedHost` Host/Origin
+// check as the HTTP path (host-check.ts) — a WebSocket handshake cannot carry the JSON+CSRF guard, so
+// the loopback-origin check (which rejects opaque `Origin: null` and any non-loopback origin) plus the
+// capability gate are the load-bearing cross-origin defenses. SDP/ICE payloads are opaque,
+// `secret-bearing` strings: they are forwarded verbatim through the Model Gateway egress seam and are
+// never logged or persisted (privacy-contract §2/§4). Transcript text is `reviewable-text`: it is run
+// through `stripUnsafeFormatChars` and the BFF redactor before it may enter the bounded replay buffer.
+// Raw audio is never a control message (a binary frame is rejected) and is never persisted (AC1/AC6).
+import { WebSocketServer } from "ws";
+import { findConfiguredCapability, requestRealtimeNegotiation, resolveRealtimeVoice, resolveVoiceCapability, selectRealtimeVoiceModel, } from "@oscharko-dev/keiko-model-gateway";
+import { CONVERSATION_SYSTEM_PROMPT } from "./conversation-prompt.js";
+import { DEFAULT_VOICE_PROTOCOL_TIMEOUTS, isVoiceReplayEligible, stripUnsafeFormatChars, validateVoiceControlMessage, VOICE_PERSONAS, VOICE_PROFILE_NEGOTIATION_MODE, VOICE_PROTOCOL_VERSION, voiceMessageAllowedForProfile, } from "@oscharko-dev/keiko-contracts";
+import { retrieveMemoryContext } from "@oscharko-dev/keiko-memory-retrieval";
+import { isAllowedHost } from "./host-check.js";
+import { currentGatewayConfig, currentGatewayEgressConfig } from "./deps.js";
+import { isVoiceDisabledByPolicy, isVoiceRealtimeCapable } from "./read-handlers.js";
+import { conversationMemoryScopes, resolveConversationMemoryContext, } from "./memory-conversation-context.js";
+import { vaultAsQueryPort } from "./memory-conv-handlers.js";
+// The single loopback path the BFF WebSocket upgrade is re-opened for. Every other upgrade keeps the
+// hard 404 + socket.destroy() default (server.ts).
+export const VOICE_CONTROL_PATH = "/api/voice/control";
+// An SDP offer is small (a single audio m-line plus ICE/DTLS metadata); reject a larger one before
+// any provider call so a hostile client cannot push an unbounded body through the egress seam.
+const MAX_OFFER_SDP_BYTES = 256_000;
+// Reviewable transcript text is bounded before strip/redact so a hostile client cannot grow the
+// replay buffer without limit.
+const MAX_TRANSCRIPT_CHARS = 8_000;
+// The bounded per-session replay-diagnostic record (AC6): the host re-delivers these `replayable`
+// host→client events to a reconnecting client. Oldest entries are evicted past the cap.
+const MAX_REPLAY_EVENTS = 200;
+// A disconnected session is resumable (by idempotency key) for this long, then swept.
+const SESSION_RESUME_TTL_MS = 60_000;
+// Bound the number of tracked sessions on the loopback control plane (single local user).
+const MAX_ACTIVE_SESSIONS = 64;
+const MAX_REALTIME_CONTEXT_MESSAGES = 12;
+const MAX_REALTIME_CONTEXT_CHARS = 12_000;
+// Bound the identifier length/charset before a client-chosen id may be tracked or logged, so a
+// hostile id cannot inject into a log/audit line (content-free redaction class, protocol §8).
+const MAX_ID_LENGTH = 200;
+// Printable ASCII, no control characters, quotes, or whitespace.
+const SAFE_IDENTIFIER = /^[\x21-\x7e]+$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSafeIdentifier(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_ID_LENGTH &&
+        SAFE_IDENTIFIER.test(value));
+}
+function isVoicePersona(value) {
+    return typeof value === "string" && VOICE_PERSONAS.includes(value);
+}
+function isVoiceSessionChatContext(value) {
+    if (!isRecord(value) || !isSafeIdentifier(value.chatId)) {
+        return false;
+    }
+    if (value.memory !== undefined && !isVoiceSessionMemoryContext(value.memory)) {
+        return false;
+    }
+    return value.grounding === undefined || isVoiceSessionGroundingContext(value.grounding);
+}
+function isVoiceSessionMemoryContext(value) {
+    if (!isRecord(value) || typeof value.enabled !== "boolean") {
+        return false;
+    }
+    const budgetTokens = value.budgetTokens;
+    return (budgetTokens === undefined ||
+        (typeof budgetTokens === "number" && Number.isInteger(budgetTokens) && budgetTokens >= 0));
+}
+function isVoiceSessionGroundingContext(value) {
+    if (!isRecord(value) || typeof value.enabled !== "boolean") {
+        return false;
+    }
+    const sourceCount = value.sourceCount;
+    if (typeof sourceCount !== "number" || !Number.isInteger(sourceCount) || sourceCount < 0) {
+        return false;
+    }
+    return (value.kind === "files" ||
+        value.kind === "knowledge" ||
+        value.kind === "hybrid" ||
+        value.kind === "multi");
+}
+// Resolves the configured realtime-voice provider to negotiate against, or undefined when none is
+// configured/usable. Mirrors voice-handlers.ts resolveSttProvider.
+function resolveRealtimeProvider(config) {
+    const modelId = selectRealtimeVoiceModel(config);
+    if (modelId === undefined) {
+        return undefined;
+    }
+    return config.providers.find((provider) => provider.modelId === modelId);
+}
+// The spoken-dialogue persona for the realtime session. It is the SAME Keiko system persona the text
+// chat uses (CONVERSATION_SYSTEM_PROMPT) plus a short voice-delivery addendum, so spoken and written
+// Keiko cannot diverge. Setting it explicitly replaces the provider's default demo persona ("a helpful,
+// witty, and friendly AI … Talk quickly … knowledge cutoff 2023-10"), which would otherwise make the
+// realtime voice a separate, ungrounded assistant — a direct violation of the dialogue-mode invariant.
+const REALTIME_SPOKEN_ADDENDUM = " You are speaking with the user by voice. Keep replies short, natural, and conversational. " +
+    "Do not read code, file paths, or long identifiers aloud verbatim; summarize them in words.";
+const REALTIME_GROUNDED_VOICE_ADDENDUM = " This voice session is connected to Keiko grounding sources. For any substantive question about " +
+    "the connected repository, files, documents, knowledge capsules, or project context, call the " +
+    "search_keiko_grounding tool before giving the final answer. You may briefly say that you are " +
+    "checking, but do not state factual conclusions until the tool result is available. After the tool " +
+    "result arrives, speak the answer faithfully and do not add unsupported facts.";
+const REALTIME_GROUNDING_TOOL = {
+    type: "function",
+    name: "search_keiko_grounding",
+    description: "Search Keiko's connected repository, file, document, and knowledge sources for the current chat and return a citation-backed answer.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            query: {
+                type: "string",
+                description: "The user's grounded question, rewritten only enough to preserve the intended meaning.",
+            },
+        },
+        required: ["query"],
+    },
+};
+// Whisper transcription enables input-audio transcripts so the chat transcript can capture what the
+// user said by voice (the dialogue-mode grounding/evidence path).
+const DEFAULT_REALTIME_TRANSCRIPTION_MODEL = "whisper-1";
+// Realtime SDP negotiation is interactive: a user is waiting with the microphone open. The generic
+// provider request timeout (commonly 30s) is far too long here — a hung provider would freeze the
+// session on "negotiating" for half a minute before surfacing an error. Clamp to a short interactive
+// bound so a stalled handshake fails fast and the composer can degrade to text.
+const REALTIME_NEGOTIATION_TIMEOUT_MS = 8_000;
+function trimContextText(text) {
+    const safe = stripUnsafeFormatChars(text).trim();
+    return safe.length <= MAX_REALTIME_CONTEXT_CHARS
+        ? safe
+        : safe.slice(-MAX_REALTIME_CONTEXT_CHARS);
+}
+function recentChatContext(deps, chatId) {
+    const messages = deps.store
+        .listMessages(chatId, MAX_REALTIME_CONTEXT_MESSAGES)
+        .filter((message) => message.role === "user" || message.role === "assistant");
+    const text = messages
+        .map((message) => `${message.role === "user" ? "User" : "Assistant"}: ${message.content}`)
+        .join("\n");
+    return trimContextText(text);
+}
+function isRouteLikeResult(value) {
+    return isRecord(value) && typeof value.status === "number";
+}
+function shouldIncludeRealtimeMemory(deps, chatContext) {
+    return (chatContext?.memory?.enabled === true &&
+        deps.memoryVault !== undefined &&
+        chatContext.chatId.length > 0);
+}
+function latestRealtimeMemoryQuery(deps, chatId, fallback) {
+    return (deps.store
+        .listMessages(chatId, MAX_REALTIME_CONTEXT_MESSAGES)
+        .filter((message) => message.role === "user")
+        .at(-1)?.content ?? fallback);
+}
+function realtimeMemoryContext(deps, chatContext) {
+    if (!shouldIncludeRealtimeMemory(deps, chatContext)) {
+        return "";
+    }
+    const memoryVault = deps.memoryVault;
+    if (memoryVault === undefined) {
+        return "";
+    }
+    const chat = deps.store.findChatById(chatContext.chatId);
+    if (chat === undefined) {
+        return "";
+    }
+    const runtime = resolveConversationMemoryContext(deps, chat.projectPath, chat.id);
+    if (isRouteLikeResult(runtime)) {
+        return "";
+    }
+    const queryText = latestRealtimeMemoryQuery(deps, chat.id, chat.title);
+    try {
+        const retrieval = retrieveMemoryContext({
+            scopes: conversationMemoryScopes(runtime),
+            queryText,
+            ...(chatContext.memory.budgetTokens !== undefined
+                ? { budgetTokens: chatContext.memory.budgetTokens }
+                : {}),
+            nowMs: Date.now(),
+        }, vaultAsQueryPort(memoryVault));
+        return trimContextText(retrieval.contextBlock.text);
+    }
+    catch {
+        return "";
+    }
+}
+function realtimeInstructions(deps, chatContext) {
+    const sections = [`${CONVERSATION_SYSTEM_PROMPT}${REALTIME_SPOKEN_ADDENDUM}`];
+    if (chatContext?.grounding?.enabled === true) {
+        sections.push(REALTIME_GROUNDED_VOICE_ADDENDUM);
+    }
+    if (chatContext !== undefined) {
+        const recent = recentChatContext(deps, chatContext.chatId);
+        if (recent.length > 0) {
+            sections.push(`Current Keiko chat context:\n${recent}`);
+        }
+        const memory = realtimeMemoryContext(deps, chatContext);
+        if (memory.length > 0) {
+            sections.push(`MemoriaViva context available for this voice session:\n${memory}`);
+        }
+    }
+    return sections.join("\n\n");
+}
+function realtimeGroundingEnabled(chatContext) {
+    return chatContext?.grounding?.enabled === true;
+}
+function realtimeProviderSupportsTools(config, provider) {
+    const capability = findConfiguredCapability(config, provider.modelId);
+    if (capability === undefined) {
+        return true;
+    }
+    return capability.toolCalling || capability.supportsRealtimeVoice === true;
+}
+// Resolves the realtime session voice from the provider's persona→voice mapping, guarded to a
+// realtime-valid id. Without an explicit voice the session would use the provider default; with a
+// TTS-only id (e.g. the operator-config `nova`) the realtime model rejects the session. The client's
+// selected persona wins when mapped; otherwise the neutral persona, then the first configured profile,
+// are the fallbacks — every result passes through `resolveRealtimeVoice` so it is always realtime-valid.
+function resolveRealtimeVoiceId(provider, persona) {
+    const profiles = provider.voiceProfiles ?? [];
+    const selected = persona !== undefined
+        ? profiles.find((profile) => profile.persona === persona)?.voiceId
+        : undefined;
+    const neutral = profiles.find((profile) => profile.persona === "neutral")?.voiceId;
+    return resolveRealtimeVoice(selected ?? neutral ?? profiles[0]?.voiceId);
+}
+function buildNegotiationRequest(provider, offerSdp, persona, instructions, groundingEnabled, toolsSupported, deps, signal) {
+    const egress = provider.egress ?? currentGatewayEgressConfig(deps);
+    return {
+        endpoint: provider.baseUrl,
+        apiKey: provider.apiKey,
+        ...(provider.apiKeyHeaderName !== undefined
+            ? { apiKeyHeaderName: provider.apiKeyHeaderName }
+            : {}),
+        ...(provider.realtimeAuthMode !== undefined
+            ? { realtimeAuthMode: provider.realtimeAuthMode }
+            : {}),
+        modelId: provider.modelId,
+        instructions,
+        voiceId: resolveRealtimeVoiceId(provider, persona),
+        transcriptionModel: DEFAULT_REALTIME_TRANSCRIPTION_MODEL,
+        ...(groundingEnabled && toolsSupported
+            ? { tools: [REALTIME_GROUNDING_TOOL], toolChoice: "auto" }
+            : {}),
+        offerSdp,
+        signal,
+        timeoutMs: Math.min(provider.timeoutMs, REALTIME_NEGOTIATION_TIMEOUT_MS),
+        ...(egress !== undefined ? { egress } : {}),
+    };
+}
+// The protocol state machine for one attached control socket. Pure of WebSocket/IO concerns beyond
+// the injected `socket.send` — every inbound frame is validated against the #496 contract, gated by
+// the session profile, and answered per the protocol; every outbound frame is sequenced, redacted,
+// and (when replay-eligible) buffered. Negotiation is delegated to the injected `negotiate` seam.
+export class VoiceControlConnection {
+    socket;
+    session;
+    negotiate;
+    redact;
+    negotiation;
+    closed = false;
+    constructor(options) {
+        this.socket = options.socket;
+        this.session = options.session;
+        this.negotiate = options.negotiate;
+        this.redact = options.redact;
+    }
+    // Re-delivers the buffered replayable events to a (re)attached client, then announces the resolved
+    // session — the reconnect catch-up of protocol §7. The control transport is `loopback-websocket`,
+    // recorded per session so the contract's `VOICE_CONTROL_TRANSPORT_V1` baseline is never mutated.
+    start(resume) {
+        if (resume) {
+            for (const buffered of this.session.replay) {
+                this.dispatchOut(buffered);
+            }
+        }
+        this.emit({
+            kind: "session.created",
+            profile: this.session.profile,
+            controlTransport: "loopback-websocket",
+            mediaTransport: "webrtc",
+            negotiationMode: VOICE_PROFILE_NEGOTIATION_MODE[this.session.profile],
+            ...(this.session.providerLocality !== undefined
+                ? { providerLocality: this.session.providerLocality }
+                : {}),
+        });
+        this.emit({
+            kind: "capability.offer",
+            profile: this.session.profile,
+            capabilities: { speechToText: true, speechOutput: true, realtimeVoice: true },
+        });
+    }
+    async receive(raw) {
+        if (this.closed) {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.fail("invalid-message");
+            return;
+        }
+        const validation = validateVoiceControlMessage(parsed);
+        if (!validation.ok) {
+            // The envelope (including the version-compatibility rule) is malformed. If the version is the
+            // problem, answer the protocol's dedicated unsupported-version error before closing.
+            const code = isRecord(parsed) && parsed.protocolVersion !== VOICE_PROTOCOL_VERSION
+                ? "unsupported-version"
+                : "invalid-message";
+            this.fail(code);
+            return;
+        }
+        const message = parsed;
+        // Idempotency on (sessionId, seq): an already-seen or stale client sequence is ignored, never
+        // re-processed (protocol §7). session.create is the resume anchor and is always handled.
+        if (message.kind !== "session.create" && message.seq <= this.session.lastClientSeq) {
+            return;
+        }
+        if (!voiceMessageAllowedForProfile(message.kind, this.session.profile)) {
+            this.emitError("not-allowed-for-profile");
+            return;
+        }
+        this.session.lastClientSeq = Math.max(this.session.lastClientSeq, message.seq);
+        await this.dispatchIn(message);
+    }
+    // Aborts any in-flight negotiation and marks the connection closed (socket lifecycle ended). The
+    // session record is retained by the plane for the resume window; this only detaches the socket.
+    dispose() {
+        this.closed = true;
+        this.negotiation?.abort();
+        this.negotiation = undefined;
+    }
+    async dispatchIn(message) {
+        // Only the kinds that drive a host action are handled. Every other permitted kind is an
+        // observable no-op: a repeated session.create (start() already announced the session), a late
+        // signal.ice.candidate (proxied single-shot SDP carries ICE in the offer/answer — no provider
+        // trickle channel), client-reported media.track.state / transcript.partial / playback.state, and
+        // any host-originated kind a client should not send. A future contract kind is likewise ignored —
+        // unknown control messages are never trusted.
+        switch (message.kind) {
+            case "signal.sdp.offer":
+                await this.handleOffer(message.sdp);
+                return;
+            case "capability.select":
+                // The only selectable profile is the resolved full-realtime profile; acknowledge by policy.
+                this.emit({ kind: "policy.decision", decision: "allow" });
+                return;
+            case "control.interrupt":
+                // Barge-in is observed on the control plane; the actual interruption happens on the media
+                // plane. Acknowledge playback interruption so the state is observable (AC6).
+                this.emit({ kind: "playback.state", state: "interrupted" });
+                return;
+            case "control.cancel":
+                this.cancelNegotiation();
+                return;
+            case "transcript.committed":
+                this.recordTranscript(message.text);
+                return;
+            case "transcript.discarded":
+                // Replayable + content-free: record it into the reconnect buffer without echoing.
+                this.record({ kind: "transcript.discarded" });
+                return;
+            case "session.close":
+                this.emit({ kind: "session.closed", reason: "client-request" });
+                this.shutdown(1000, "session closed");
+                return;
+            default:
+                return;
+        }
+    }
+    cancelNegotiation() {
+        this.negotiation?.abort();
+        this.negotiation = undefined;
+    }
+    async handleOffer(offerSdp) {
+        if (typeof offerSdp !== "string" || offerSdp.length === 0 || !offerSdp.startsWith("v=")) {
+            this.emitError("invalid-message");
+            return;
+        }
+        if (Buffer.byteLength(offerSdp, "utf8") > MAX_OFFER_SDP_BYTES) {
+            this.emitError("invalid-message");
+            return;
+        }
+        this.emit({ kind: "media.track.state", track: "audio-in", state: "negotiating" });
+        const controller = new AbortController();
+        this.negotiation = controller;
+        let outcome;
+        try {
+            outcome = await this.negotiate(offerSdp, this.session.persona, this.session.chatContext, controller.signal);
+        }
+        catch {
+            outcome = { ok: false, kind: "transport" };
+        }
+        if (this.negotiation !== controller) {
+            // A cancel/close superseded this negotiation; drop its result.
+            return;
+        }
+        this.negotiation = undefined;
+        if (this.closed) {
+            return;
+        }
+        if (!outcome.ok) {
+            this.emitError("negotiation-failed");
+            this.emit({ kind: "media.track.state", track: "audio-in", state: "ended" });
+            return;
+        }
+        // signal.sdp.answer is ephemeral + secret-bearing: it is sent to the live negotiation but never
+        // buffered into the replay record (emit() only buffers replay-eligible kinds).
+        this.emit({ kind: "signal.sdp.answer", sdp: outcome.value.answerSdp });
+        this.emit({ kind: "media.track.state", track: "audio-in", state: "live" });
+        this.emit({ kind: "media.track.state", track: "audio-out", state: "live" });
+    }
+    recordTranscript(text) {
+        if (typeof text !== "string") {
+            return;
+        }
+        // reviewable-text: neutralise Trojan-source / bidi rendering before the text may enter the replay
+        // buffer (protocol §8). Bounded length. A
+        // committed transcript the client relayed from the provider is recorded into the reconnect buffer
+        // (it is `replayable`) but not echoed back to the client that already holds it.
+        const safe = stripUnsafeFormatChars(text).slice(0, MAX_TRANSCRIPT_CHARS);
+        this.record({ kind: "transcript.committed", text: safe });
+    }
+    emitError(code) {
+        this.emit({ kind: "error", code });
+    }
+    // Builds a sequenced host→client control message from a payload, appends it to the bounded replay
+    // buffer when the kind is replay-eligible (protocol §7), and returns it for sending.
+    build(payload) {
+        const message = {
+            protocolVersion: VOICE_PROTOCOL_VERSION,
+            sessionId: this.session.sessionId,
+            seq: this.session.hostSeq,
+            direction: "host-to-client",
+            ...payload,
+        };
+        this.session.hostSeq += 1;
+        if (isVoiceReplayEligible(message.kind)) {
+            this.session.replay.push(message);
+            if (this.session.replay.length > MAX_REPLAY_EVENTS) {
+                this.session.replay.shift();
+            }
+        }
+        return message;
+    }
+    // Sequences, redacts, and sends a host→client message now (and buffers it when replay-eligible).
+    emit(payload) {
+        this.dispatchOut(this.build(payload));
+    }
+    // Records a replay-eligible event into the reconnect buffer WITHOUT sending it — used for durable
+    // events the client relayed (e.g. a committed transcript) which the connected client already holds,
+    // but which a future reconnect must be able to replay.
+    record(payload) {
+        this.build(payload);
+    }
+    dispatchOut(message) {
+        if (this.closed) {
+            return;
+        }
+        try {
+            this.socket.send(JSON.stringify(this.redact(message)));
+        }
+        catch {
+            // a send failure means the socket is gone; the close handler will dispose the connection.
+        }
+    }
+    fail(code) {
+        this.emitError(code);
+        this.shutdown(1008, code);
+    }
+    shutdown(code, reason) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.negotiation?.abort();
+        this.negotiation = undefined;
+        try {
+            this.socket.close(code, reason);
+        }
+        catch {
+            // ignore — socket already gone
+        }
+    }
+}
+// Reads whether a raw upgrade request targets the single allowed voice control path.
+function isVoiceControlUpgrade(req) {
+    let url;
+    try {
+        url = new URL(req.url ?? "/", "http://127.0.0.1");
+    }
+    catch {
+        return false;
+    }
+    return url.pathname === VOICE_CONTROL_PATH;
+}
+function rawDataToString(data, isBinary) {
+    if (isBinary) {
+        return undefined;
+    }
+    if (typeof data === "string") {
+        return data;
+    }
+    if (Buffer.isBuffer(data)) {
+        return data.toString("utf8");
+    }
+    if (Array.isArray(data)) {
+        return Buffer.concat(data).toString("utf8");
+    }
+    return Buffer.from(data).toString("utf8");
+}
+// One heartbeat sweep over the live control sockets: a socket that did not answer the previous ping
+// (isAlive === false) is terminated so a half-open connection cannot linger and hold a session slot;
+// every other socket is re-armed (isAlive = false) and pinged. Pure over the iterable — no clock, no
+// timer — so it is directly unit-testable without a real WebSocket server.
+export function sweepControlHeartbeat(sockets) {
+    for (const socket of sockets) {
+        if (socket.isAlive === false) {
+            socket.terminate();
+            continue;
+        }
+        socket.isAlive = false;
+        socket.ping();
+    }
+}
+function readSessionCreateFrame(ws, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        ws.close(1008, "invalid opening frame");
+        return undefined;
+    }
+    if (!validateVoiceControlMessage(parsed).ok || !isRecord(parsed) || parsed.kind !== "session.create") {
+        ws.close(1008, "expected session.create");
+        return undefined;
+    }
+    return parsed;
+}
+function sessionCreateMatchesVoiceProfile(parsed, voice) {
+    return (parsed.requestedProfile === voice.profile &&
+        parsed.negotiationMode === VOICE_PROFILE_NEGOTIATION_MODE[voice.profile]);
+}
+function resolveSessionChatContext(ws, deps, sessionId, parsed) {
+    if (!isVoiceSessionChatContext(parsed.chatContext)) {
+        emitStandaloneError(ws, sessionId, "not-allowed-for-profile", deps.redactor);
+        ws.close(1008, "missing chat context");
+        return undefined;
+    }
+    const chatContext = parsed.chatContext;
+    if (deps.store.findChatById(chatContext.chatId) === undefined) {
+        emitStandaloneError(ws, sessionId, "not-allowed-for-profile", deps.redactor);
+        ws.close(1008, "unknown chat context");
+        return undefined;
+    }
+    return chatContext;
+}
+class VoiceControlPlaneImpl {
+    planeDeps;
+    wss = new WebSocketServer({ noServer: true });
+    sessions = new Map();
+    // Liveness sweep timer, started lazily on the first connection and cleared on closeAll (shutdown).
+    // A socket that misses a ping/pong cycle is terminated by the next sweep.
+    heartbeat;
+    constructor(planeDeps) {
+        this.planeDeps = planeDeps;
+    }
+    startHeartbeat() {
+        if (this.heartbeat !== undefined) {
+            return;
+        }
+        const timer = setInterval(() => {
+            sweepControlHeartbeat(this.wss.clients);
+        }, DEFAULT_VOICE_PROTOCOL_TIMEOUTS.heartbeatIntervalMs);
+        // Do not keep the Node process alive solely for the heartbeat.
+        timer.unref();
+        this.heartbeat = timer;
+    }
+    handleUpgrade(req, sock, head) {
+        if (!isVoiceControlUpgrade(req)) {
+            return false;
+        }
+        const deps = this.planeDeps.handlerDeps();
+        // Three load-bearing gates: (1) a present, loopback Origin — a browser always sends Origin on a WS
+        // handshake, so requiring it (in addition to `isAllowedHost` rejecting a non-loopback or opaque
+        // `null` Origin) keeps the control plane reachable only from the loopback browser origin and never
+        // from a non-browser local process; (2) loopback Host; (3) the full-realtime capability gate (a
+        // no-voice / STT-only / policy-disabled deployment keeps the WebSocket hard-rejected, AC1/AC3).
+        if (typeof req.headers.origin !== "string" ||
+            !isAllowedHost(req, this.planeDeps.port) ||
+            !isVoiceRealtimeCapable(deps)) {
+            return false;
+        }
+        this.wss.handleUpgrade(req, sock, head, (ws) => {
+            this.onConnection(ws, deps);
+        });
+        return true;
+    }
+    closeAll() {
+        if (this.heartbeat !== undefined) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = undefined;
+        }
+        for (const client of this.wss.clients) {
+            client.close(1001, "server shutting down");
+        }
+        this.wss.close();
+        this.sessions.clear();
+    }
+    sweepExpired(now) {
+        for (const [key, state] of this.sessions) {
+            if (state.detachedAt !== undefined && now - state.detachedAt > SESSION_RESUME_TTL_MS) {
+                this.sessions.delete(key);
+            }
+        }
+    }
+    buildNegotiate(deps) {
+        return async (offerSdp, persona, chatContext, signal) => {
+            const config = currentGatewayConfig(deps);
+            if (config === undefined) {
+                return { ok: false, kind: "unsupported-model" };
+            }
+            const provider = resolveRealtimeProvider(config);
+            if (provider === undefined) {
+                return { ok: false, kind: "unsupported-model" };
+            }
+            const negotiate = deps.voiceRealtimeNegotiationRequest ?? requestRealtimeNegotiation;
+            const instructions = realtimeInstructions(deps, chatContext);
+            const groundingEnabled = realtimeGroundingEnabled(chatContext);
+            const toolsSupported = realtimeProviderSupportsTools(config, provider);
+            if (groundingEnabled && !toolsSupported) {
+                return { ok: false, kind: "unsupported-model" };
+            }
+            return negotiate(buildNegotiationRequest(provider, offerSdp, persona, instructions, groundingEnabled, toolsSupported, deps, signal));
+        };
+    }
+    // Resolves (creating or resuming) the session for a validated opening frame, or closes the socket
+    // and returns undefined on a bad frame. The negotiation mode must match the canonical mode for the
+    // effective profile (an inconsistent mode is rejected, never advisory).
+    resolveSession(ws, deps, voice, raw) {
+        const parsed = readSessionCreateFrame(ws, raw);
+        if (parsed === undefined)
+            return undefined;
+        const sessionId = parsed.sessionId;
+        if (!isSafeIdentifier(sessionId) || !isSafeIdentifier(parsed.idempotencyKey)) {
+            ws.close(1008, "invalid session identifiers");
+            return undefined;
+        }
+        if (!sessionCreateMatchesVoiceProfile(parsed, voice)) {
+            emitStandaloneError(ws, sessionId, "not-allowed-for-profile", deps.redactor);
+            ws.close(1008, "profile/negotiation mismatch");
+            return undefined;
+        }
+        // Optional, content-free persona: validated against the closed VOICE_PERSONAS set. An absent or
+        // malformed value is treated as "no preference" (undefined) rather than rejected, so a stale client
+        // can never break session creation; the voice then falls back to the configured default.
+        const persona = isVoicePersona(parsed.persona) ? parsed.persona : undefined;
+        const chatContext = resolveSessionChatContext(ws, deps, sessionId, parsed);
+        if (chatContext === undefined)
+            return undefined;
+        return this.createOrResumeSession(ws, voice, sessionId, parsed.idempotencyKey, persona, chatContext, deps.redactor);
+    }
+    createOrResumeSession(ws, voice, sessionId, idempotencyKey, persona, chatContext, redact) {
+        this.sweepExpired(Date.now());
+        const resumed = this.sessions.get(idempotencyKey);
+        if (resumed?.sessionId === sessionId) {
+            resumed.detachedAt = undefined;
+            return { state: resumed, resume: true };
+        }
+        if (this.sessions.size >= MAX_ACTIVE_SESSIONS) {
+            emitStandaloneError(ws, sessionId, "rate-limited", redact);
+            ws.close(1013, "too many sessions");
+            return undefined;
+        }
+        const state = {
+            sessionId,
+            idempotencyKey,
+            profile: voice.profile,
+            providerLocality: voice.providerLocality,
+            persona,
+            chatContext,
+            hostSeq: 0,
+            lastClientSeq: 0,
+            replay: [],
+            detachedAt: undefined,
+        };
+        this.sessions.set(idempotencyKey, state);
+        return { state, resume: false };
+    }
+    // Heartbeat liveness for one socket: mark it alive, refresh on each pong, and ensure the sweep timer
+    // is running. A socket that stops answering pings is terminated by the next sweep (no half-open leaks).
+    attachHeartbeat(ws) {
+        const live = ws;
+        live.isAlive = true;
+        ws.on("pong", () => {
+            live.isAlive = true;
+        });
+        this.startHeartbeat();
+    }
+    onConnection(ws, deps) {
+        this.attachHeartbeat(ws);
+        const voice = resolveVoiceCapability(currentGatewayConfig(deps) ?? { providers: [] }, {
+            policyDisabled: isVoiceDisabledByPolicy(deps.env),
+        });
+        const negotiate = this.buildNegotiate(deps);
+        const socket = {
+            send: (data) => {
+                ws.send(data);
+            },
+            close: (code, reason) => {
+                ws.close(code, reason);
+            },
+        };
+        let connection;
+        let activeSession;
+        ws.on("message", (data, isBinary) => {
+            const raw = rawDataToString(data, isBinary);
+            if (raw === undefined) {
+                // Raw audio / binary frames are never a control message (AC1): reject and close.
+                ws.close(1003, "binary frames are not permitted on the control plane");
+                return;
+            }
+            if (connection !== undefined) {
+                void connection.receive(raw);
+                return;
+            }
+            const resolved = this.resolveSession(ws, deps, voice, raw);
+            if (resolved === undefined) {
+                return;
+            }
+            activeSession = resolved.state;
+            connection = new VoiceControlConnection({
+                socket,
+                session: resolved.state,
+                negotiate,
+                redact: deps.redactor,
+            });
+            connection.start(resolved.resume);
+        });
+        ws.on("close", () => {
+            connection?.dispose();
+            // Mark the session resumable for the reconnect window rather than deleting it immediately.
+            if (activeSession !== undefined && activeSession.detachedAt === undefined) {
+                activeSession.detachedAt = Date.now();
+            }
+        });
+        ws.on("error", () => {
+            ws.close(1011, "control plane error");
+        });
+    }
+}
+// Builds the realtime voice control plane bound to one server.
+export function createVoiceControlPlane(planeDeps) {
+    return new VoiceControlPlaneImpl(planeDeps);
+}
+// Emits a standalone protocol error on a socket that has no attached connection yet (e.g. a rejected
+// opening frame), so the client receives a typed error before the close, redacted like every frame.
+function emitStandaloneError(ws, sessionId, code, redact) {
+    const message = {
+        protocolVersion: VOICE_PROTOCOL_VERSION,
+        sessionId,
+        seq: 0,
+        direction: "host-to-client",
+        kind: "error",
+        code,
+    };
+    try {
+        ws.send(JSON.stringify(redact(message)));
+    }
+    catch {
+        // ignore — socket already gone
+    }
+}