@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/server/websocket/handler.js

@@ -7,10 +7,40 @@ import { validateApiKey } from '../auth/api-keys.js';
 import { logger } from "../../utils/logger.js";
 import { isOriginAllowed } from '../origin-check.js';
 import { verifyToken } from '../auth/jwt.js';
+import { isDirectLoopbackRequest } from '../middleware/auth.js';
 import { authenticateDevice, getGatewayPairingStore, isDevicePairingRequired } from '../../gateway/device-pairing.js';
 import { gatewayServerVersion, GATEWAY_PROTOCOL_VERSION } from '../../gateway/protocol.js';
 import { TIMEOUT_CONFIG, SERVER_CONFIG } from '../../config/constants.js';
-import { createServerAgent, runAgentCompletion, streamAgentDeltas, } from '../agent-adapter.js';
+import { peekUserFacingFailoverNotice } from '../../providers/provider-failover-user-notice.js';
+import { applyChatReplyContext, readClientMsgId } from '../mobile/chat-extras.js';
+import { assertVoiceNoteDuration, assertVoiceNoteDurationSync, isAudioMime, sniffAudioMime, synthesizeMobileVoiceReply, transcribeVoiceAttachment, WS_MAX_VOICE_BYTES, } from '../mobile/voice-note.js';
+function parsePositiveMsEnv(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function resolveWsHeartbeatIntervalMs(env = process.env) {
+    return parsePositiveMsEnv(env.CODEBUDDY_WS_HEARTBEAT_INTERVAL_MS, TIMEOUT_CONFIG.WS_HEARTBEAT_INTERVAL);
+}
+export function resolveWsIdleTimeoutMs(env = process.env) {
+    return parsePositiveMsEnv(env.CODEBUDDY_WS_IDLE_TIMEOUT_MS, TIMEOUT_CONFIG.WS_IDLE_TIMEOUT);
+}
+/** True when the heartbeat sweeper should kill this socket as idle. */
+/** Lane timeout for peer:* RPCs. Longer than the 120s channel default so a local LLM can finish. */
+export const PEER_REQUEST_LANE_TIMEOUT_MS = 15 * 60 * 1000;
+export function shouldTerminateIdleWs(state, now, idleTimeoutMs) {
+    if (state.peerHandlersActive > 0 || state.streaming || state.activeTurn) {
+        return false;
+    }
+    return now - state.lastActivity > idleTimeoutMs;
+}
+import { createServerAgent, streamAgentDeltas, } from '../agent-adapter.js';
+import { isMobilePwaEnabled } from '../mobile/index.js';
+import { sniffImageMime } from '../../companion/companion-photo.js';
+import { unwireMobileConfirmationBridge, wireMobileConfirmationBridge } from './confirmation-bridge.js';
+import { getAvatarRendererRegistry } from '../../avatar/avatar-renderer-registry.js';
+import { appendCompanionHistory, loadMobileCompanionHistory, saveMobileCompanionHistory, } from '../../companion/mobile-history.js';
 // Lazy import to avoid circular dependency through channels/index.ts
 let _enqueueMessage;
 async function getEnqueueMessage() {
@@ -26,12 +56,215 @@ const RATE_LIMITS = {
     authWindowMs: 60000, // 1 minute window for auth
     messagesPerMinute: 60, // Max messages per minute
     toolExecutionsPerMinute: 20, // Max tool executions per minute
+    peerRequestsPerMinute: 30, // LLM-capable peer RPC calls per minute
 };
+const MAX_PARALLEL_PEER_HANDLERS = 3;
+const MAX_PENDING_PEER_HANDLERS = 200;
 // Active connections
 const connections = new Map();
 // Epoch ms when the WS server last started (for gateway uptime in `status`).
 let serverStartedAt = 0;
 const messageHandlers = new Map();
+const laneBypassMessageTypes = new Set(['stop']);
+function extensionPrincipal(state) {
+    let id = `connection:${state.id}`;
+    let source = 'websocket:connection';
+    if (state.userId) {
+        id = `user:${state.userId}`;
+        source = 'websocket:user';
+    }
+    else if (state.keyId) {
+        id = `key:${state.keyId}`;
+        source = 'websocket:api-key';
+    }
+    else if (state.deviceId) {
+        id = `device:${state.deviceId}`;
+        source = 'websocket:device';
+    }
+    return Object.freeze({
+        id,
+        source,
+        scopes: Object.freeze(state.authenticated ? [...state.scopes] : []),
+        loopback: state.loopback === true,
+        secure: state.secure === true,
+        anonymousRemote: state.anonymousRemote === true,
+    });
+}
+function createExtensionContext(ws, state) {
+    return Object.freeze({
+        connectionId: state.id,
+        principal: extensionPrincipal(state),
+        send(message) {
+            if (ws.readyState !== 1)
+                return false;
+            ws.send(JSON.stringify(message));
+            return true;
+        },
+        isBackpressured(maxBufferedBytes) {
+            if (ws.readyState !== 1)
+                return true;
+            return ws.bufferedAmount >= Math.max(0, maxBufferedBytes);
+        },
+        onClose(listener) {
+            if (state.extensionsCleaned) {
+                listener();
+                return () => undefined;
+            }
+            const listeners = state.extensionCloseHandlers ?? new Set();
+            state.extensionCloseHandlers = listeners;
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    });
+}
+function cleanupWebSocketExtensions(state) {
+    if (state.extensionsCleaned)
+        return;
+    state.extensionsCleaned = true;
+    const listeners = state.extensionCloseHandlers;
+    state.extensionCloseHandlers = undefined;
+    if (!listeners)
+        return;
+    for (const listener of listeners) {
+        try {
+            listener();
+        }
+        catch (error) {
+            logger.warn('[ws] extension close hook failed', {
+                connectionId: state.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    listeners.clear();
+}
+function resetWebSocketExtensionsForIdentityChange(state) {
+    state.approvalCapable = false;
+    cleanupWebSocketExtensions(state);
+    state.extensionsCleaned = false;
+    // A new principal on the same socket must never inherit the previous one's
+    // companion conversation.
+    state.companionHistory = undefined;
+}
+/**
+ * Add a message type without leaking the underlying socket or ConnectionState.
+ * The returned function removes exactly this registration and is idempotent.
+ */
+export function registerWebSocketExtension(registration) {
+    if (!/^[a-z][a-z0-9_.:-]{0,127}$/.test(registration.type)) {
+        throw new Error(`Invalid WebSocket extension type: ${registration.type}`);
+    }
+    if (messageHandlers.has(registration.type)) {
+        throw new Error(`WebSocket message type already registered: ${registration.type}`);
+    }
+    const handler = async (ws, state, payload, envelope) => {
+        await registration.handle(createExtensionContext(ws, state), payload, envelope);
+    };
+    messageHandlers.set(registration.type, handler);
+    if (registration.bypassLane)
+        laneBypassMessageTypes.add(registration.type);
+    let registered = true;
+    return () => {
+        if (!registered)
+            return;
+        registered = false;
+        if (messageHandlers.get(registration.type) === handler) {
+            messageHandlers.delete(registration.type);
+        }
+        if (registration.bypassLane)
+            laneBypassMessageTypes.delete(registration.type);
+    };
+}
+/**
+ * Cancel the current turn without throwing from a socket lifecycle callback.
+ * The per-turn flag is authoritative for suppressing any late provider delta
+ * or terminal response after the abort signal has been delivered.
+ */
+function abortActiveTurn(state) {
+    const turn = state.activeTurn;
+    if (!turn || turn.cancelled)
+        return false;
+    turn.cancelled = true;
+    state.streaming = false;
+    if (state.agent) {
+        turn.abortDelivered = true;
+        try {
+            state.agent.abortCurrentOperation();
+        }
+        catch (error) {
+            logger.debug('[ws] agent abort failed', {
+                connectionId: state.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return true;
+}
+/** Most photos accepted on one mobile message. */
+export const WS_MAX_CHAT_ATTACHMENTS = 4;
+/** Per-photo base64 ceiling. The PWA resizes to ~200 KB before sending. */
+export const WS_MAX_ATTACHMENT_BYTES = 600 * 1024;
+/**
+ * Validate the attachments of a `chat` frame. The payload is remote input:
+ * the count, each size and the actual image type are checked here, and the
+ * type comes from the DECODED BYTES — a declared `mimeType` is never proof.
+ */
+function readDeclaredDurationMs(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0)
+        return undefined;
+    return raw;
+}
+export function validateChatAttachments(raw, opts = {}) {
+    if (raw === undefined || raw === null)
+        return { ok: true, attachments: [] };
+    if (!Array.isArray(raw))
+        return { ok: false, error: 'Attachments must be an array' };
+    if (raw.length > WS_MAX_CHAT_ATTACHMENTS) {
+        return { ok: false, error: `At most ${WS_MAX_CHAT_ATTACHMENTS} photos per message` };
+    }
+    const attachments = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== 'object') {
+            return { ok: false, error: 'Each attachment must be an object' };
+        }
+        const data = entry.data;
+        if (typeof data !== 'string' || data.trim().length === 0) {
+            return { ok: false, error: 'Attachment data must be a base64 string' };
+        }
+        const payload = data.startsWith('data:') ? data.slice(data.indexOf(',') + 1) : data;
+        if (!/^[A-Za-z0-9+/\r\n]*={0,2}$/.test(payload)) {
+            return { ok: false, error: 'Attachment data must be base64' };
+        }
+        const bytes = Buffer.from(payload, 'base64');
+        if (bytes.length === 0)
+            return { ok: false, error: 'Attachment is empty' };
+        const image = sniffImageMime(bytes);
+        if (image) {
+            if (bytes.length > WS_MAX_ATTACHMENT_BYTES) {
+                return {
+                    ok: false,
+                    error: `Each photo must be at most ${Math.floor(WS_MAX_ATTACHMENT_BYTES / 1024)} KB`,
+                };
+            }
+            attachments.push({ mimeType: image, data: payload });
+            continue;
+        }
+        const audio = sniffAudioMime(bytes);
+        if (audio) {
+            if (bytes.length > WS_MAX_VOICE_BYTES) {
+                return { ok: false, error: 'Each voice note must be at most 2 MB' };
+            }
+            const declared = readDeclaredDurationMs(entry.durationMs ?? opts.declaredDurationMs);
+            const duration = assertVoiceNoteDurationSync(bytes, declared);
+            if (!duration.ok)
+                return duration;
+            attachments.push({ mimeType: audio, data: payload });
+            continue;
+        }
+        return { ok: false, error: 'Attachment is not an image' };
+    }
+    return { ok: true, attachments };
+}
 /**
  * Generate connection ID
  */
@@ -66,6 +299,7 @@ export function buildConnectedGreeting(opts) {
  */
 export function buildGatewayStatus(input) {
     const c = input.connection;
+    const notice = peekUserFacingFailoverNotice();
     return {
         type: 'status',
         payload: {
@@ -84,6 +318,9 @@ export function buildGatewayStatus(input) {
                 pairingRequired: input.server.pairingRequired,
                 connections: input.connections,
             },
+            ...(notice
+                ? { failoverNotice: notice.text, failoverNoticeKind: notice.kind }
+                : {}),
         },
         timestamp: new Date().toISOString(),
     };
@@ -96,6 +333,13 @@ function send(ws, message) {
         ws.send(JSON.stringify(message));
     }
 }
+function sendChatAck(ws, ack, clientMsgId) {
+    send(ws, {
+        type: 'ack',
+        payload: { ack, ...(clientMsgId ? { clientMsgId } : {}) },
+        timestamp: new Date().toISOString(),
+    });
+}
 /**
  * Check and increment rate limit counter. Returns true if within limit.
  */
@@ -119,6 +363,43 @@ function sendError(ws, code, message, id) {
         timestamp: new Date().toISOString(),
     });
 }
+function startPeerHandler(state, task) {
+    state.peerHandlersActive += 1;
+    void task.run()
+        .then(task.resolve, task.reject)
+        .finally(() => {
+        state.peerHandlersActive = Math.max(0, state.peerHandlersActive - 1);
+        const next = state.peerHandlerQueue.shift();
+        if (next)
+            startPeerHandler(state, next);
+    });
+}
+/**
+ * Bound peer RPC concurrency independently from serial chat/tool messages.
+ * The shared LaneQueue only admits parallel work that was pending in the same
+ * batch, so requests arriving while a long handler is running also need this
+ * small per-connection scheduler to preserve true RPC multiplexing.
+ */
+function enqueuePeerHandler(state, run) {
+    return new Promise((resolve, reject) => {
+        const task = { run, resolve, reject };
+        if (state.peerHandlersActive < MAX_PARALLEL_PEER_HANDLERS) {
+            startPeerHandler(state, task);
+            return;
+        }
+        if (state.peerHandlerQueue.length >= MAX_PENDING_PEER_HANDLERS) {
+            reject(new Error('Peer request queue has too many pending tasks'));
+            return;
+        }
+        state.peerHandlerQueue.push(task);
+    });
+}
+function rejectQueuedPeerHandlers(state, reason) {
+    const error = new Error(reason);
+    for (const task of state.peerHandlerQueue.splice(0)) {
+        task.reject(error);
+    }
+}
 /**
  * Handle authentication message
  */
@@ -127,13 +408,19 @@ messageHandlers.set('authenticate', async (ws, state, payload) => {
         sendError(ws, 'RATE_LIMITED', 'Too many authentication attempts. Please wait before retrying.');
         return;
     }
-    const { token, apiKey } = payload;
+    const { token, apiKey, approvalCapable } = payload;
     if (apiKey) {
         const key = validateApiKey(apiKey);
         if (key) {
+            resetWebSocketExtensionsForIdentityChange(state);
             state.authenticated = true;
             state.keyId = key.id;
+            state.userId = undefined;
+            state.deviceId = undefined;
             state.scopes = key.scopes;
+            state.anonymousRemote = false;
+            if (approvalCapable === true)
+                state.approvalCapable = true;
             send(ws, {
                 type: 'authenticated',
                 payload: { keyId: key.id, scopes: key.scopes },
@@ -151,12 +438,18 @@ messageHandlers.set('authenticate', async (ws, state, payload) => {
         }
         const decoded = verifyToken(token, jwtSecret);
         if (decoded) {
+            resetWebSocketExtensionsForIdentityChange(state);
             state.authenticated = true;
-            state.userId = decoded.userId;
+            state.userId = decoded.userId ?? decoded.sub;
+            state.keyId = undefined;
+            state.deviceId = undefined;
             state.scopes = decoded.scopes || ['chat'];
+            state.anonymousRemote = false;
+            if (approvalCapable === true)
+                state.approvalCapable = true;
             send(ws, {
                 type: 'authenticated',
-                payload: { userId: decoded.userId, scopes: state.scopes },
+                payload: { userId: state.userId, scopes: state.scopes },
                 timestamp: new Date().toISOString(),
             });
             return;
@@ -174,9 +467,15 @@ messageHandlers.set('authenticate', async (ws, state, payload) => {
         ...(auth.requestedScopes ? { requestedScopes: auth.requestedScopes } : {}),
     });
     if (deviceOutcome.outcome === 'authenticated') {
+        resetWebSocketExtensionsForIdentityChange(state);
         state.authenticated = true;
         state.deviceId = deviceOutcome.deviceId;
+        state.userId = undefined;
+        state.keyId = undefined;
         state.scopes = deviceOutcome.scopes ?? [];
+        state.anonymousRemote = false;
+        if (approvalCapable === true)
+            state.approvalCapable = true;
         send(ws, {
             type: 'authenticated',
             payload: { deviceId: deviceOutcome.deviceId, scopes: state.scopes, paired: true },
@@ -194,10 +493,120 @@ messageHandlers.set('authenticate', async (ws, state, payload) => {
     }
     sendError(ws, 'AUTH_FAILED', 'Invalid credentials');
 });
+/**
+ * Lisa's reply for the mobile PWA (`assistant: 'companion'`).
+ *
+ * Delegates to `runCompanionTurn` — the SINGLE companion path, shared with the
+ * channels surface: cached selfie first, then the companion profile (persona
+ * spoken prompt + relational context + history) through the provider the
+ * server is configured for. It no longer calls `defaultReply`, which is the
+ * VOICE loop (fastest-model routing, empty history) and stays untouched.
+ */
+export async function produceCompanionReply(message, options = {}) {
+    const { runCompanionTurn } = await import('../../companion/companion-turn.js');
+    const result = await runCompanionTurn(message, {
+        surface: 'mobile',
+        includeImageBytes: true,
+        ...(options.history ? { history: options.history } : {}),
+        ...(options.attachments?.length ? { attachments: options.attachments } : {}),
+    });
+    if (result.image || result.kind === 'selfie') {
+        return {
+            text: result.text,
+            ...(result.image ? { image: result.image } : {}),
+            kind: result.kind,
+        };
+    }
+    return result.text;
+}
+/** Persistence identity for this connection, or undefined (memory-only). */
+function companionHistoryIdentity(state) {
+    return state.userId ?? state.deviceId ?? state.keyId;
+}
+/**
+ * The connection's companion history, restored once from disk on first use so
+ * a phone that reconnected mid-conversation does not start from nothing.
+ */
+function companionHistoryFor(state) {
+    if (!state.companionHistory) {
+        state.companionHistory = loadMobileCompanionHistory(companionHistoryIdentity(state));
+    }
+    return state.companionHistory;
+}
+/** Record one companion exchange; never stores image bytes. */
+function rememberCompanionTurn(state, userText, produced) {
+    const assistantText = typeof produced === 'string' ? produced : produced.text;
+    const kind = typeof produced === 'string' ? undefined : produced.kind;
+    state.companionHistory = appendCompanionHistory(companionHistoryFor(state), [
+        { role: 'user', content: userText },
+        {
+            role: 'assistant',
+            content: assistantText,
+            ...(kind === 'selfie' ? { kind: 'selfie' } : {}),
+        },
+    ]);
+    saveMobileCompanionHistory(companionHistoryIdentity(state), state.companionHistory);
+}
+async function producePeerReply(peerId, message) {
+    const { getFleetRegistry } = await import('../../fleet/fleet-registry.js');
+    const entry = getFleetRegistry().get(peerId);
+    if (!entry) {
+        throw new Error(`Unknown fleet peer: ${peerId}`);
+    }
+    const result = await entry.listener.request('peer.chat', { prompt: message });
+    if (result && typeof result === 'object' && typeof result.text === 'string') {
+        return result.text;
+    }
+    return typeof result === 'string' ? result : JSON.stringify(result ?? '');
+}
+async function runPlainChatTurn(ws, state, turn, options) {
+    const messageId = `msg_${Date.now()}`;
+    if (options.stream) {
+        state.streaming = true;
+        send(ws, {
+            type: 'stream_start',
+            id: messageId,
+            timestamp: new Date().toISOString(),
+        });
+        sendChatAck(ws, 'read', options.clientMsgId);
+    }
+    const produced = await options.produce();
+    const content = typeof produced === 'string' ? produced : produced.text;
+    const image = typeof produced === 'string' ? undefined : produced.image;
+    if (turn.cancelled)
+        return;
+    if (options.stream) {
+        if (content || image) {
+            send(ws, {
+                type: 'stream_chunk',
+                id: messageId,
+                payload: { delta: content, ...(image ? { image } : {}) },
+                timestamp: new Date().toISOString(),
+            });
+        }
+        send(ws, {
+            type: 'stream_end',
+            id: messageId,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    else {
+        sendChatAck(ws, 'read', options.clientMsgId);
+        send(ws, {
+            type: 'chat_response',
+            payload: { content, finishReason: 'stop', ...(image ? { image } : {}) },
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
 /**
  * Handle chat message
  */
 messageHandlers.set('chat', async (ws, state, payload) => {
+    if (state.anonymousRemote) {
+        sendError(ws, 'REMOTE_AUTH_REQUIRED', 'Remote agent chat requires authentication');
+        return;
+    }
     if (!state.authenticated) {
         sendError(ws, 'UNAUTHORIZED', 'Authentication required');
         return;
@@ -210,21 +619,13 @@ messageHandlers.set('chat', async (ws, state, payload) => {
         sendError(ws, 'RATE_LIMITED', 'Message rate limit exceeded. Please slow down.');
         return;
     }
-    const { message, model, stream = true, sessionId: _sessionId } = payload;
-    // Validate message
-    if (!message) {
-        sendError(ws, 'INVALID_REQUEST', 'Message is required');
-        return;
-    }
-    if (typeof message !== 'string') {
+    const { message, model, stream = true, sessionId: _sessionId, assistant: assistantRaw, peerId: peerIdRaw, attachments: attachmentsRaw, replyTo: replyToRaw, clientMsgId: clientMsgIdRaw, voiceReply: voiceReplyRaw, durationMs: durationMsRaw, } = payload;
+    if (message !== undefined && message !== null && typeof message !== 'string') {
         sendError(ws, 'INVALID_REQUEST', 'Message must be a string');
         return;
     }
-    if (message.trim().length === 0) {
-        sendError(ws, 'INVALID_REQUEST', 'Message cannot be empty or whitespace only');
-        return;
-    }
-    if (message.length > 100000) {
+    const rawMessage = typeof message === 'string' ? message : '';
+    if (rawMessage.length > 100000) {
         sendError(ws, 'INVALID_REQUEST', 'Message exceeds maximum length of 100000 characters');
         return;
     }
@@ -235,13 +636,100 @@ messageHandlers.set('chat', async (ws, state, payload) => {
             return;
         }
     }
+    const turn = { cancelled: false, abortDelivered: false };
+    state.activeTurn = turn;
+    const assistant = typeof assistantRaw === 'string' ? assistantRaw.trim() : 'agent';
+    const peerId = typeof peerIdRaw === 'string' ? peerIdRaw.trim() : '';
+    // Photos are accepted only for the companion; every other assistant keeps the
+    // exact payload contract it had.
+    const declaredDurationMs = readDeclaredDurationMs(durationMsRaw);
+    const validatedAttachments = validateChatAttachments(assistant === 'companion' ? attachmentsRaw : undefined, { declaredDurationMs });
+    if (!validatedAttachments.ok) {
+        sendError(ws, 'INVALID_REQUEST', validatedAttachments.error);
+        return;
+    }
+    const audioAttachments = validatedAttachments.attachments.filter((item) => isAudioMime(item.mimeType));
+    const imageAttachments = validatedAttachments.attachments.filter((item) => item.mimeType.startsWith('image/'));
+    for (const audio of audioAttachments) {
+        const duration = await assertVoiceNoteDuration(Buffer.from(audio.data, 'base64'), declaredDurationMs);
+        if (!duration.ok) {
+            sendError(ws, 'INVALID_REQUEST', duration.error);
+            return;
+        }
+    }
+    if (rawMessage.trim().length === 0 && audioAttachments.length === 0) {
+        sendError(ws, 'INVALID_REQUEST', message ? 'Message cannot be empty or whitespace only' : 'Message is required');
+        return;
+    }
+    let userText = applyChatReplyContext(rawMessage, replyToRaw).trim();
+    if (audioAttachments[0] && assistant === 'companion') {
+        const transcript = await transcribeVoiceAttachment(audioAttachments[0]);
+        if (transcript) {
+            userText =
+                userText && userText !== '(message vocal)' ? `${userText}\n\n${transcript}` : transcript;
+        }
+        else if (!userText) {
+            userText = '(message vocal)';
+        }
+    }
+    if (!userText) {
+        sendError(ws, 'INVALID_REQUEST', 'Message cannot be empty or whitespace only');
+        return;
+    }
+    const clientMsgId = readClientMsgId(clientMsgIdRaw);
+    sendChatAck(ws, 'received', clientMsgId);
+    const wantVoiceReply = voiceReplyRaw === true;
     try {
+        if (assistant === 'companion') {
+            let spoken = '';
+            await runPlainChatTurn(ws, state, turn, {
+                stream,
+                clientMsgId,
+                produce: async () => {
+                    const history = companionHistoryFor(state);
+                    const produced = await produceCompanionReply(userText, {
+                        history,
+                        ...(imageAttachments.length ? { attachments: imageAttachments } : {}),
+                    });
+                    spoken = typeof produced === 'string' ? produced : produced.text;
+                    if (!turn.cancelled)
+                        rememberCompanionTurn(state, userText, produced);
+                    return produced;
+                },
+            });
+            if (wantVoiceReply && spoken && !turn.cancelled) {
+                const audio = await synthesizeMobileVoiceReply(spoken);
+                if (audio) {
+                    send(ws, {
+                        type: 'audio',
+                        payload: audio,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+            }
+            return;
+        }
+        const resolvedPeerId = peerId || (assistant.startsWith('peer:') ? assistant.slice(5) : '');
+        if (assistant === 'peer' || resolvedPeerId) {
+            const target = resolvedPeerId || assistant;
+            if (!target || target === 'peer' || target === 'agent' || target === 'companion') {
+                sendError(ws, 'INVALID_REQUEST', 'peerId is required for peer chat');
+                return;
+            }
+            await runPlainChatTurn(ws, state, turn, {
+                stream,
+                clientMsgId,
+                produce: () => producePeerReply(target, userText),
+            });
+            return;
+        }
         // Lazy load agent (with mutex to prevent duplicate creation)
         if (!state.agent) {
             if (!state.agentInitializing) {
                 state.agentInitializing = (async () => {
                     try {
                         state.agent = await createServerAgent();
+                        state.agent.setRecoverySessionId?.(state.id);
                     }
                     catch (err) {
                         state.agentInitializing = undefined;
@@ -255,6 +743,16 @@ messageHandlers.set('chat', async (ws, state, payload) => {
         if (!agent) {
             throw new Error('Agent initialization failed');
         }
+        // A stop/close can arrive while the lazy agent is being constructed. In
+        // that case deliver the abort as soon as the agent exists and never start
+        // a provider turn.
+        if (turn.cancelled) {
+            if (!turn.abortDelivered) {
+                turn.abortDelivered = true;
+                agent.abortCurrentOperation();
+            }
+            return;
+        }
         if (stream) {
             state.streaming = true;
             const messageId = `msg_${Date.now()}`;
@@ -264,9 +762,10 @@ messageHandlers.set('chat', async (ws, state, payload) => {
                 id: messageId,
                 timestamp: new Date().toISOString(),
             });
-            const streamGen = streamAgentDeltas(agent, message, { model });
+            sendChatAck(ws, 'read', clientMsgId);
+            const streamGen = streamAgentDeltas(agent, userText, { model, surface: 'websocket' });
             for await (const delta of streamGen) {
-                if (!state.streaming)
+                if (turn.cancelled || !state.streaming)
                     break;
                 if (delta) {
                     send(ws, {
@@ -277,38 +776,63 @@ messageHandlers.set('chat', async (ws, state, payload) => {
                     });
                 }
             }
-            // Send stream end
-            send(ws, {
-                type: 'stream_end',
-                id: messageId,
-                timestamp: new Date().toISOString(),
-            });
+            if (!turn.cancelled) {
+                // Only a naturally-completed stream receives stream_end. An explicit
+                // cancellation is represented by stream_stopped from the stop handler.
+                send(ws, {
+                    type: 'stream_end',
+                    id: messageId,
+                    timestamp: new Date().toISOString(),
+                });
+            }
             state.streaming = false;
         }
         else {
-            // Non-streaming response
-            const result = await runAgentCompletion(agent, message, { model });
-            send(ws, {
-                type: 'chat_response',
-                payload: {
-                    content: result.content,
-                    finishReason: result.finishReason,
-                },
-                timestamp: new Date().toISOString(),
-            });
+            // Use the streaming agent path internally even when the wire response is
+            // non-streaming. CodeBuddyAgent's sequential collector has no abort
+            // controller, while processUserMessageStream does; buffering its deltas
+            // preserves the single chat_response protocol and makes stop/close/error
+            // capable of releasing a blocked provider and the per-connection lane.
+            let content = '';
+            for await (const delta of streamAgentDeltas(agent, userText, {
+                model,
+                surface: 'websocket',
+            })) {
+                if (turn.cancelled)
+                    break;
+                content += delta;
+            }
+            if (!turn.cancelled) {
+                sendChatAck(ws, 'read', clientMsgId);
+                send(ws, {
+                    type: 'chat_response',
+                    payload: {
+                        content,
+                        finishReason: 'stop',
+                    },
+                    timestamp: new Date().toISOString(),
+                });
+            }
         }
     }
     catch (error) {
         state.streaming = false;
-        sendError(ws, 'CHAT_ERROR', error instanceof Error ? error.message : String(error));
+        if (!turn.cancelled) {
+            sendError(ws, 'CHAT_ERROR', error instanceof Error ? error.message : String(error));
+        }
+    }
+    finally {
+        state.streaming = false;
+        if (state.activeTurn === turn) {
+            state.activeTurn = undefined;
+        }
     }
 });
 /**
  * Handle stop streaming
  */
 messageHandlers.set('stop', async (ws, state, _payload) => {
-    if (state.streaming) {
-        state.streaming = false;
+    if (abortActiveTurn(state)) {
         send(ws, {
             type: 'stream_stopped',
             timestamp: new Date().toISOString(),
@@ -363,6 +887,7 @@ messageHandlers.set('execute_tool', async (ws, state, payload) => {
                 state.agentInitializing = (async () => {
                     try {
                         state.agent = await createServerAgent();
+                        state.agent.setRecoverySessionId?.(state.id);
                     }
                     catch (err) {
                         state.agentInitializing = undefined;
@@ -404,7 +929,27 @@ messageHandlers.set('ping', async (ws, _state, _payload) => {
 /**
  * Handle get status
  */
-messageHandlers.set('status', async (ws, state, _payload) => {
+messageHandlers.set('status', async (ws, state, payload) => {
+    if (payload
+        && typeof payload === 'object'
+        && !Array.isArray(payload)
+        && payload.approvalCapable === true) {
+        if (state.authenticated && !state.anonymousRemote && state.scopes.includes('tools')) {
+            state.approvalCapable = true;
+        }
+        else {
+            state.approvalCapable = false;
+            logger.warn('[ws] status approvalCapable ignored — requires authenticated non-anonymous socket with tools scope', {
+                connectionId: state.id,
+                authenticated: state.authenticated,
+                anonymousRemote: state.anonymousRemote,
+                scopes: state.scopes,
+            });
+        }
+    }
+    else {
+        state.approvalCapable = false;
+    }
     send(ws, buildGatewayStatus({
         connection: {
             connectionId: state.id,
@@ -425,6 +970,95 @@ messageHandlers.set('status', async (ws, state, _payload) => {
         connections: getConnectionStats(),
     }));
 });
+/** Rebuild a MetaHuman renderer after reconnecting without replaying stale audio. */
+messageHandlers.set('avatar.sync', async (ws, state, _payload) => {
+    if (!state.authenticated) {
+        sendError(ws, 'UNAUTHORIZED', 'Authentication required');
+        return;
+    }
+    const { buildAvatarSyncMessage, canReadAvatarEvents } = await import('../../avatar/avatar-gateway-bridge.js');
+    if (!canReadAvatarEvents(state.scopes)) {
+        sendError(ws, 'FORBIDDEN', 'avatar:read scope required');
+        return;
+    }
+    const [{ getAvatarEventBus }, { getAvatarRendererRegistry }] = await Promise.all([
+        import('../../avatar/avatar-event-bus.js'),
+        import('../../avatar/avatar-renderer-registry.js'),
+    ]);
+    send(ws, buildAvatarSyncMessage(getAvatarEventBus().history(24), new Date(), getAvatarRendererRegistry().list()));
+});
+/** Register an Unreal/simulator renderer so Code Buddy knows its capabilities. */
+messageHandlers.set('avatar.renderer.hello', async (ws, state, payload) => {
+    if (!state.authenticated) {
+        sendError(ws, 'UNAUTHORIZED', 'Authentication required');
+        return;
+    }
+    if (state.anonymousRemote) {
+        sendError(ws, 'REMOTE_AUTH_REQUIRED', 'Remote avatar renderers require authentication');
+        return;
+    }
+    const { canReportAvatarStatus } = await import('../../avatar/avatar-gateway-bridge.js');
+    if (!canReportAvatarStatus(state.scopes)) {
+        sendError(ws, 'FORBIDDEN', 'avatar:write scope required');
+        return;
+    }
+    const { getAvatarRendererRegistry } = await import('../../avatar/avatar-renderer-registry.js');
+    const result = getAvatarRendererRegistry().register(state.id, payload);
+    if (!result.ok) {
+        sendError(ws, 'INVALID_AVATAR_RENDERER', result.error);
+        return;
+    }
+    send(ws, {
+        type: 'avatar.renderer.ack',
+        payload: { kind: 'hello', renderer: result.renderer },
+        timestamp: new Date().toISOString(),
+    });
+});
+/** Receive bounded playback/health feedback from the active MetaHuman renderer. */
+messageHandlers.set('avatar.renderer.status', async (ws, state, payload) => {
+    if (!state.authenticated) {
+        sendError(ws, 'UNAUTHORIZED', 'Authentication required');
+        return;
+    }
+    if (state.anonymousRemote) {
+        sendError(ws, 'REMOTE_AUTH_REQUIRED', 'Remote avatar renderers require authentication');
+        return;
+    }
+    const { canReportAvatarStatus } = await import('../../avatar/avatar-gateway-bridge.js');
+    if (!canReportAvatarStatus(state.scopes)) {
+        sendError(ws, 'FORBIDDEN', 'avatar:write scope required');
+        return;
+    }
+    const { getAvatarRendererRegistry } = await import('../../avatar/avatar-renderer-registry.js');
+    const result = getAvatarRendererRegistry().report(state.id, payload);
+    if (!result.ok) {
+        sendError(ws, 'INVALID_AVATAR_STATUS', result.error);
+        return;
+    }
+    send(ws, {
+        type: 'avatar.renderer.ack',
+        payload: { kind: 'status', renderer: result.renderer },
+        timestamp: new Date().toISOString(),
+    });
+});
+/** Inspect renderer readiness without exposing conversation or audio content. */
+messageHandlers.set('avatar.status', async (ws, state, _payload) => {
+    if (!state.authenticated) {
+        sendError(ws, 'UNAUTHORIZED', 'Authentication required');
+        return;
+    }
+    const { canReadAvatarEvents } = await import('../../avatar/avatar-gateway-bridge.js');
+    if (!canReadAvatarEvents(state.scopes)) {
+        sendError(ws, 'FORBIDDEN', 'avatar:read scope required');
+        return;
+    }
+    const { getAvatarRendererRegistry } = await import('../../avatar/avatar-renderer-registry.js');
+    send(ws, {
+        type: 'avatar.status',
+        payload: { renderers: getAvatarRendererRegistry().list() },
+        timestamp: new Date().toISOString(),
+    });
+});
 /**
  * Phase (d).13 — peer:request RPC handler. Routes to the peer-rpc
  * registry. Caller must hold the `peer:invoke` scope (analogous to
@@ -439,10 +1073,25 @@ messageHandlers.set('peer:request', async (ws, state, payload) => {
         sendError(ws, 'FORBIDDEN', 'peer:invoke scope required');
         return;
     }
-    const { dispatchPeerRequest } = await import('./peer-rpc.js');
     // payload is the request frame { id, method, params, traceId?, depth? }
     const frame = (payload ?? {});
     const requestId = frame.id ?? '';
+    if (!checkRateLimit(state, 'peerRequestCount', 'peerWindowStart', RATE_LIMITS.peerRequestsPerMinute, 60_000)) {
+        send(ws, {
+            type: 'peer:response',
+            payload: {
+                id: requestId || 'unknown',
+                ok: false,
+                error: {
+                    code: 'RATE_LIMITED',
+                    message: 'Peer request rate limit exceeded. Please slow down.',
+                },
+            },
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
+    const { dispatchPeerRequest } = await import('./peer-rpc.js');
     // Phase (d).19 — emitChunk forwards a partial result delta to the
     // caller as a `peer:chunk` frame keyed by the same request id. The
     // caller's FleetListener routes chunks to its onChunk callback. We
@@ -482,17 +1131,26 @@ messageHandlers.set('peer:request', async (ws, state, payload) => {
  * Process incoming message
  */
 async function processMessage(ws, state, data) {
-    let message;
+    let decoded;
     try {
-        message = JSON.parse(data.toString());
+        decoded = JSON.parse(data.toString());
     }
     catch {
         sendError(ws, 'INVALID_JSON', 'Invalid JSON message');
         return;
     }
+    if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) {
+        sendError(ws, 'INVALID_MESSAGE', 'Message must be a JSON object');
+        return;
+    }
+    const message = decoded;
     state.lastActivity = Date.now();
-    const { type, id, payload } = message;
-    if (!type) {
+    const { type, payload } = message;
+    const id = typeof message.id === 'string' ? message.id.slice(0, 256) : undefined;
+    const requestId = typeof message.requestId === 'string'
+        ? message.requestId.slice(0, 256)
+        : undefined;
+    if (typeof type !== 'string' || type.length === 0 || type.length > 128) {
         sendError(ws, 'INVALID_MESSAGE', 'Message type is required', id);
         return;
     }
@@ -501,16 +1159,61 @@ async function processMessage(ws, state, data) {
         sendError(ws, 'UNKNOWN_TYPE', `Unknown message type: ${type}`, id);
         return;
     }
+    // Cancellation must not wait behind the active chat turn in the per-socket
+    // lane queue; otherwise a blocked provider can never receive its abort.
+    const envelope = {
+        ...(id ? { id } : {}),
+        ...(requestId ? { requestId } : {}),
+    };
+    if (laneBypassMessageTypes.has(type)) {
+        try {
+            await handler(ws, state, payload ?? {}, envelope);
+        }
+        catch (error) {
+            sendError(ws, 'HANDLER_ERROR', error instanceof Error ? error.message : String(error), id);
+        }
+        return;
+    }
     // Use the connection ID as the session key for lane queue serialization.
     // This ensures messages from the same WebSocket connection are processed
     // serially while different connections run in parallel.
     const sessionKey = `ws:${state.id}`;
     try {
         const enqueueMessage = await getEnqueueMessage();
-        await enqueueMessage(sessionKey, () => handler(ws, state, payload || {}));
+        if (type === 'peer:request') {
+            const frame = payload && typeof payload === 'object'
+                ? payload
+                : {};
+            const peerRequestId = typeof frame.id === 'string' ? frame.id : 'unknown';
+            await enqueuePeerHandler(state, () => enqueueMessage(`${sessionKey}:peer:${peerRequestId}`, () => handler(ws, state, payload ?? {}, envelope), {
+                parallel: true,
+                // Channel default is 120s; cold local Ollama peer.chat exceeded it (GK17).
+                timeout: PEER_REQUEST_LANE_TIMEOUT_MS,
+            }));
+        }
+        else {
+            await enqueueMessage(sessionKey, () => handler(ws, state, payload ?? {}, envelope));
+        }
     }
     catch (error) {
-        sendError(ws, 'HANDLER_ERROR', error instanceof Error ? error.message : String(error), id);
+        const message = error instanceof Error ? error.message : String(error);
+        if (type === 'peer:request') {
+            const frame = payload && typeof payload === 'object'
+                ? payload
+                : {};
+            send(ws, {
+                type: 'peer:response',
+                payload: {
+                    id: typeof frame.id === 'string' ? frame.id : 'unknown',
+                    ok: false,
+                    error: { code: 'HANDLER_ERROR', message },
+                },
+                timestamp: new Date().toISOString(),
+            });
+        }
+        else {
+            sendError(ws, 'HANDLER_ERROR', message, id);
+        }
     }
 }
 /**
@@ -520,9 +1223,21 @@ export async function setupWebSocket(server, config) {
     // Dynamic import ws
     const { WebSocketServer } = await import('ws');
     serverStartedAt = Date.now();
+    if (isMobilePwaEnabled()) {
+        unwireMobileConfirmationBridge();
+        wireMobileConfirmationBridge({
+            broadcast,
+            collectApprovalSurfaceIds,
+            registerExtension: registerWebSocketExtension,
+        });
+    }
+    else {
+        unwireMobileConfirmationBridge();
+    }
     const wss = new WebSocketServer({
         server,
         path: '/ws',
+        maxPayload: SERVER_CONFIG.WS_MAX_PAYLOAD_BYTES,
         verifyClient: (info, cb) => {
             // Non-browser clients (CLI, fleet peers via the `ws` library) send no Origin
             // header — allow them. Browser clients must present an allowed Origin, which
@@ -546,12 +1261,35 @@ export async function setupWebSocket(server, config) {
             cb(false, 403, 'Forbidden origin');
         },
     });
-    wss.on('connection', (ws, _req) => {
+    wss.on('connection', (ws, req) => {
         const now = Date.now();
+        const loopback = isDirectLoopbackRequest(req.socket.remoteAddress, req.headers);
         const state = {
             id: generateConnectionId(),
             authenticated: !config.authEnabled, // Auto-auth if auth disabled
-            scopes: config.authEnabled ? [] : ['chat', 'tools', 'sessions', 'memory'],
+            scopes: config.authEnabled
+                ? []
+                : [
+                    'chat',
+                    'tools',
+                    'sessions',
+                    'memory',
+                    'avatar:read',
+                    'avatar:write',
+                    ...(loopback
+                        ? [
+                            'cognition:write',
+                            'cognition:write-local',
+                            'cognition:sense',
+                            'cognition:read',
+                            'cognition:read-local',
+                            'cognition:raw',
+                        ]
+                        : []),
+                ],
+            anonymousRemote: !config.authEnabled && !loopback,
+            loopback,
+            secure: Boolean(req.socket.encrypted),
             lastActivity: now,
             streaming: false,
             authAttempts: 0,
@@ -560,10 +1298,18 @@ export async function setupWebSocket(server, config) {
             messageWindowStart: now,
             toolCount: 0,
             toolWindowStart: now,
+            peerRequestCount: 0,
+            peerWindowStart: now,
+            peerHandlersActive: 0,
+            peerHandlerQueue: [],
             droppedBroadcasts: 0,
         };
         connections.set(ws, state);
-        // Send welcome message (enriched with server identity + advertised capabilities)
+        ws.on('message', async (data) => {
+            await processMessage(ws, state, data);
+        });
+        // Greeting after the message listener so the first client frame cannot
+        // be dropped (connected is what clients wait on before authenticate).
         send(ws, buildConnectedGreeting({
             connectionId: state.id,
             authRequired: config.authEnabled,
@@ -572,22 +1318,40 @@ export async function setupWebSocket(server, config) {
             protocolVersion: GATEWAY_PROTOCOL_VERSION,
             methods: Array.from(messageHandlers.keys()),
         }));
-        ws.on('message', async (data) => {
-            await processMessage(ws, state, data);
+        // Protocol pings must count as activity. /fleet listen is receive-only
+        // after auth; a slow peer.chat also sends no application frames. Without
+        // this, WS_IDLE_TIMEOUT (60s) kills live fleet sockets (GK17).
+        ws.on('pong', () => {
+            state.lastActivity = Date.now();
         });
         ws.on('close', () => {
+            state.approvalCapable = false;
+            rejectQueuedPeerHandlers(state, 'WebSocket closed before peer request execution');
+            abortActiveTurn(state);
+            cleanupWebSocketExtensions(state);
             connections.delete(ws);
+            getAvatarRendererRegistry().disconnectConnection(state.id);
         });
         ws.on('error', (error) => {
             logger.error(`WebSocket error [${state.id}]:`, error);
+            state.approvalCapable = false;
+            rejectQueuedPeerHandlers(state, 'WebSocket failed before peer request execution');
+            abortActiveTurn(state);
+            cleanupWebSocketExtensions(state);
             connections.delete(ws);
+            getAvatarRendererRegistry().disconnectConnection(state.id);
         });
     });
     // Heartbeat to detect stale connections
+    const heartbeatIntervalMs = resolveWsHeartbeatIntervalMs();
+    const idleTimeoutMs = resolveWsIdleTimeoutMs();
     const heartbeatInterval = setInterval(() => {
         const now = Date.now();
         for (const [ws, state] of connections.entries()) {
-            if (now - state.lastActivity > TIMEOUT_CONFIG.WS_IDLE_TIMEOUT) {
+            if (shouldTerminateIdleWs(state, now, idleTimeoutMs)) {
+                state.approvalCapable = false;
+                abortActiveTurn(state);
+                cleanupWebSocketExtensions(state);
                 ws.terminate();
                 connections.delete(ws);
             }
@@ -597,7 +1361,7 @@ export async function setupWebSocket(server, config) {
                 }
             }
         }
-    }, TIMEOUT_CONFIG.WS_HEARTBEAT_INTERVAL);
+    }, heartbeatIntervalMs);
     wss.on('close', () => {
         clearInterval(heartbeatInterval);
     });
@@ -640,26 +1404,40 @@ function getBroadcastBufferLimit() {
     }
     return SERVER_CONFIG.WS_BROADCAST_BUFFER_LIMIT;
 }
-/**
- * Broadcast message to all authenticated connections.
- *
- * Phase (d).7 — drop-on-overflow: if a client's ws.bufferedAmount has
- * grown past WS_BROADCAST_BUFFER_LIMIT (default 2 MiB, env-overridable
- * via CODEBUDDY_FLEET_BROADCAST_BUFFER_LIMIT), this call is skipped for
- * that client and its `droppedBroadcasts` counter is incremented. Other
- * clients still receive the message. Prevents one stuck remote Claude
- * from inflating the server's ws send buffer indefinitely.
- *
- * Drops are logged at debug level once per 100 drops per client to keep
- * logs informative without spamming under sustained backpressure.
- */
-export function broadcast(message, scopeFilter) {
+function toBroadcastTarget(state) {
+    return {
+        id: state.id,
+        authenticated: state.authenticated,
+        scopes: state.scopes,
+        anonymousRemote: state.anonymousRemote === true,
+        approvalCapable: state.approvalCapable === true,
+    };
+}
+export function collectApprovalSurfaceIds() {
+    const ids = [];
+    for (const state of connections.values()) {
+        if (!state.authenticated)
+            continue;
+        if (state.anonymousRemote)
+            continue;
+        if (state.approvalCapable !== true)
+            continue;
+        if (!state.scopes.includes('tools'))
+            continue;
+        ids.push(state.id);
+    }
+    return ids;
+}
+export function broadcast(message, scopeFilter, targetFilter) {
+    const delivered = [];
     const limit = getBroadcastBufferLimit();
     for (const [ws, state] of connections.entries()) {
         if (!state.authenticated)
             continue;
         if (scopeFilter && !state.scopes.includes(scopeFilter))
             continue;
+        if (targetFilter && !targetFilter(toBroadcastTarget(state)))
+            continue;
         if (ws.bufferedAmount > limit) {
             state.droppedBroadcasts++;
             if (state.droppedBroadcasts % 100 === 1) {
@@ -673,13 +1451,18 @@ export function broadcast(message, scopeFilter) {
             continue;
         }
         send(ws, message);
+        delivered.push(state.id);
     }
+    return delivered;
 }
 /**
  * Close all connections
  */
 export function closeAllConnections() {
-    for (const ws of connections.keys()) {
+    for (const [ws, state] of connections.entries()) {
+        state.approvalCapable = false;
+        abortActiveTurn(state);
+        cleanupWebSocketExtensions(state);
         ws.close(1001, 'Server shutting down');
     }
     connections.clear();
@@ -698,6 +1481,8 @@ export function _registerConnectionForTests(ws, state) {
  * a close method). Use in beforeEach/afterEach.
  */
 export function _resetConnectionsForTests() {
+    for (const state of connections.values())
+        cleanupWebSocketExtensions(state);
     connections.clear();
 }
 //# sourceMappingURL=handler.js.map