@minionry/minion 0.7.36

package/dist/server/services/websocket/browser-handlers.js

@@ -0,0 +1,377 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomUUID } from 'node:crypto';
+import { deviceProfileFor } from '@minionry/browser-types';
+import { browserLog } from '../browser/debug-log.js';
+import { getBrowserDriverState } from '../browser/driver-state.js';
+import { captureException } from '../sentry.js';
+import { broadcastAgentTabState, resolveProposal, startReasoningAgent, } from './browser-agent-runtime.js';
+import { ensureTabProfileCaptured, isCapturableUrl, navigatingFormFactor, reconcileDeviceParam, recordDriverFormFactor, resetDriverFormFactor, } from './browser-device-profile.js';
+import { _resetIceConfigForTests, applyIceConfig, describeIceConfig, flushIceConfig, noteSessionArmed, } from './browser-ice-config.js';
+import { extractAgentApprove, extractAgentTask, extractAnswerEnvelope, extractBounds, extractFormFactor, extractIceEnvelope, extractIceServers, extractLeaseReleaseRequest, extractStateEnvelope, extractString, extractTabId, passThroughInputEnvelope, } from './browser-payloads.js';
+import { _resetViewerLifecycleForTests, recordDeviceInput, releaseDeviceInput, releaseViewerInput, viewerSessionFor, } from './browser-viewer-lifecycle.js';
+import { addressToViewer, canAddressViewer, MAX_HUMAN_SURFACES, viewers, } from './browser-viewer-registry.js';
+export { _resetBrowserAgentsForTests, _setBrowserAgentPlannerForTests, _setBrowserAgentReasonerForTests, _setBrowserAgentReviewerForTests, _setBrowserAgentSettleDelayForTests, broadcastAgentTabState, defaultAgentReasoner, } from './browser-agent-runtime.js';
+export { attachBrowserHostBroadcast } from './browser-host-broadcast.js';
+export { ensureTurnCredentials, getAppliedIceServers } from './browser-ice-config.js';
+export { onViewerDisconnected, onWsContextClosed } from './browser-viewer-lifecycle.js';
+const log = browserLog('handlers');
+const IF_READY_TYPES = new Set([
+    'browser_webrtc_answer',
+    'browser_webrtc_ice',
+    'browser_webrtc_state',
+    'browser_lease_release',
+]);
+const HOST_FREE_TYPES = new Set(['browser_agent_approve']);
+export function browserHostPolicy(type) {
+    if (HOST_FREE_TYPES.has(type))
+        return 'none';
+    if (IF_READY_TYPES.has(type))
+        return 'ifReady';
+    return 'start';
+}
+export function _resetBrowserWebrtcSessionForTests() {
+    viewers.clear();
+    _resetIceConfigForTests();
+    _resetViewerLifecycleForTests();
+    resetDriverFormFactor();
+}
+function inputRejected(reason, inputKind, message) {
+    return { __kind: 'input_rejected', reason, inputKind, message };
+}
+function isInputRejection(r) {
+    return r !== null && typeof r !== 'string' && r.__kind === 'input_rejected';
+}
+function logAttachCreated(viewer) {
+    log.info('attach.create', `session=${viewer.sessionId.slice(0, 8)} viewer=${viewer.viewerId.slice(0, 8)} attach=${viewer.attachId?.slice(0, 8) ?? '-'} tab=${viewer.tabId.slice(0, 8)} routable=${viewer.routable} iceServers=${describeIceConfig()} viewers=${viewers.size()}`);
+    if (viewer.routable)
+        return;
+    log.error('attach.unroutable', `session=${viewer.sessionId.slice(0, 8)} — the relay did not stamp _viewer on browser_webrtc_attach; ` +
+        'replying untargeted (every device of the Space receives this session’s signaling). Update the relay.');
+}
+function resolveNavTabId(data, ctx) {
+    const wireTabId = extractString(data, 'tabId');
+    const tabId = wireTabId ?? viewers.getByViewer(ctx.viewerId)?.tabId;
+    log('nav.tab', `tab=${tabId?.slice(0, 8) ?? 'agent-surface'} from=${wireTabId ? 'wire' : tabId ? 'viewer' : 'none'}`);
+    return tabId;
+}
+function traceBounds(bounds, sessionId) {
+    log('bounds', `w=${bounds.width} h=${bounds.height} dpr=${bounds.deviceScaleFactor ?? 1} mobile=${bounds.mobile === true} session=${sessionId?.slice(0, 8) ?? 'none(host-wide)'}`);
+    return sessionId;
+}
+const DISPATCH = {
+    browser_navigate: async (host, data, ctx) => {
+        const url = extractString(data, 'url');
+        if (!url)
+            return 'browser_navigate: missing data.url';
+        const cliReceiveAt = Date.now();
+        const tabId = resolveNavTabId(data, ctx);
+        const formFactor = await ensureTabProfileCaptured(host, tabId, navigatingFormFactor(ctx.viewerId));
+        await host.navigate(reconcileDeviceParam(url, formFactor), tabId);
+        log('navTiming.navigate', `tab=${tabId?.slice(0, 8) ?? '-'} cliReceive=${cliReceiveAt} hostDispatchMs=${Date.now() - cliReceiveAt}`);
+        return null;
+    },
+    browser_back: async (host, data, ctx) => {
+        await host.goBack(resolveNavTabId(data, ctx));
+        return null;
+    },
+    browser_forward: async (host, data, ctx) => {
+        await host.goForward(resolveNavTabId(data, ctx));
+        return null;
+    },
+    browser_reload: async (host, data, ctx) => {
+        await host.reload(resolveNavTabId(data, ctx));
+        return null;
+    },
+    browser_stop: async (host, data, ctx) => {
+        await host.stopLoading(resolveNavTabId(data, ctx));
+        return null;
+    },
+    browser_resize: async (host, data, ctx) => {
+        const bounds = extractBounds(data);
+        if (!bounds)
+            return 'browser_resize: missing width/height';
+        recordDriverFormFactor(ctx.viewerId, bounds.mobile === true ? 'mobile' : 'desktop');
+        await host.setBounds(bounds, traceBounds(bounds, viewerSessionFor(ctx.viewerId, 'bounds')));
+        return null;
+    },
+    browser_set_bounds: async (host, data, ctx) => {
+        const bounds = extractBounds(data);
+        if (!bounds)
+            return 'browser_set_bounds: missing width/height';
+        recordDriverFormFactor(ctx.viewerId, bounds.mobile === true ? 'mobile' : 'desktop');
+        await host.setBounds(bounds, traceBounds(bounds, viewerSessionFor(ctx.viewerId, 'bounds')));
+        return null;
+    },
+    browser_set_device_profile: async (host, data, ctx) => {
+        const tabId = extractString(data, 'tabId') ?? viewers.getByViewer(ctx.viewerId)?.tabId;
+        if (!tabId)
+            return 'browser_set_device_profile: missing tabId';
+        const formFactor = extractFormFactor(data);
+        if (!formFactor) {
+            return 'browser_set_device_profile: formFactor must be "desktop" or "mobile"';
+        }
+        log.info('tab.deviceProfile', `tab=${tabId.slice(0, 8)} formFactor=${formFactor}`);
+        await host.setTabDeviceProfile(tabId, deviceProfileFor(formFactor));
+        return null;
+    },
+    browser_input: async (host, data, ctx) => {
+        const ev = passThroughInputEnvelope(data);
+        if (!ev) {
+            return inputRejected('malformed', 'unknown', 'browser_input: invalid payload');
+        }
+        await host.forwardInput(ev, viewerSessionFor(ctx.viewerId, 'input'), ctx.wireTabId);
+        const tabId = ctx.wireTabId ?? viewers.getByViewer(ctx.viewerId)?.tabId;
+        if (tabId && host.getTabInfo(tabId)) {
+            recordDeviceInput(ctx.viewerId, ctx.ws, tabId);
+            getBrowserDriverState().recordViewInput(tabId, ev);
+        }
+        return null;
+    },
+    browser_tab_open: async (host, data, ctx) => {
+        const url = extractString(data, 'url') ?? 'about:blank';
+        log.info('tab.open', `viewer=${ctx.viewerId.slice(0, 8)} existingTabs=${host.getTabsSnapshot?.().tabs.length ?? '?'} url=${url === 'about:blank' ? 'about:blank' : 'set'}`);
+        const { id } = await host.openTab(url);
+        if (isCapturableUrl(url)) {
+            await ensureTabProfileCaptured(host, id, navigatingFormFactor(ctx.viewerId));
+        }
+        return null;
+    },
+    browser_tab_close: async (host, data, ctx) => {
+        const id = extractTabId(data);
+        if (!id)
+            return 'browser_tab_close: missing id';
+        log.info('tab.close', `tab=${id.slice(0, 8)} viewer=${ctx.viewerId.slice(0, 8)}`);
+        await host.closeTab(id);
+        return null;
+    },
+    browser_tab_select: async (host, data, ctx) => {
+        const id = extractTabId(data);
+        if (!id)
+            return 'browser_tab_select: missing id';
+        const viewer = viewers.getByViewer(ctx.viewerId);
+        log.info('tab.select', `tab=${id.slice(0, 8)} viewer=${ctx.viewerId.slice(0, 8)} session=${viewer?.sessionId.slice(0, 8) ?? 'none(host-wide switch)'}`);
+        releaseDeviceInput(ctx.viewerId, id);
+        if (viewer) {
+            if (viewer.tabId !== id)
+                getBrowserDriverState().releaseHeldInput(viewer.tabId);
+            viewer.tabId = id;
+            await host.switchViewerTab(viewer.sessionId, id);
+            return null;
+        }
+        await host.switchTab(id);
+        return null;
+    },
+    browser_webrtc_ice_config: async (host, data) => {
+        const iceServers = extractIceServers(data);
+        if (!iceServers)
+            return 'browser_webrtc_ice_config: invalid payload';
+        await applyIceConfig(host, iceServers);
+        return null;
+    },
+    browser_webrtc_answer: async (host, data) => {
+        const envelope = extractAnswerEnvelope(data);
+        if (!envelope)
+            return 'browser_webrtc_answer: invalid payload';
+        log.info('signal.answer', `session=${envelope.sessionId.slice(0, 8)} sdpLen=${envelope.kind === 'answer' ? envelope.sdp.length : 0} known=${viewers.getBySession(envelope.sessionId) !== undefined}`);
+        await host.signal(envelope);
+        return null;
+    },
+    browser_webrtc_ice: async (host, data) => {
+        const envelope = extractIceEnvelope(data);
+        if (!envelope)
+            return 'browser_webrtc_ice: invalid payload';
+        await host.signal(envelope);
+        return null;
+    },
+    browser_webrtc_state: async (host, data) => {
+        const envelope = extractStateEnvelope(data);
+        if (!envelope)
+            return 'browser_webrtc_state: invalid payload';
+        if (envelope.kind === 'state') {
+            log.info('signal.webState', `session=${envelope.sessionId.slice(0, 8)} state=${envelope.state} reason=${envelope.reason ?? '-'}`);
+        }
+        await host.signal(envelope);
+        if (envelope.kind === 'state' && envelope.state === 'closed') {
+            const detached = viewers.detach(envelope.sessionId);
+            if (detached)
+                releaseViewerInput(detached);
+        }
+        return null;
+    },
+    browser_webrtc_attach: async (host, data, ctx) => {
+        const requestedTabId = extractString(data, 'tabId');
+        const attachId = extractString(data, 'attachId') ?? undefined;
+        let tabId = requestedTabId;
+        if (!tabId) {
+            let first;
+            viewers.forEach((v) => { if (!first)
+                first = v; });
+            if (first)
+                tabId = first.tabId;
+        }
+        if (!tabId) {
+            return 'browser_webrtc_attach: no tabId and no live viewers to infer from';
+        }
+        const existing = viewers.getByViewer(ctx.viewerId);
+        const sameAttach = !attachId || !existing?.attachId || existing.attachId === attachId;
+        if (existing && existing.tabId === tabId && sameAttach && existing.lastState !== 'closed' && existing.lastState !== 'failed') {
+            log.info('attach.idempotentReuse', `session=${existing.sessionId.slice(0, 8)} tab=${tabId.slice(0, 8)} lastState=${existing.lastState ?? 'pending'}`);
+            return null;
+        }
+        const prior = viewers.detachByViewer(ctx.viewerId);
+        if (prior) {
+            log.info('attach.replaceExisting', `prior=${prior.sessionId.slice(0, 8)} priorState=${prior.lastState ?? 'pending'}`);
+            releaseViewerInput(prior);
+            await host.closeCaptureFor(prior.sessionId);
+        }
+        if (!prior && viewers.size() >= MAX_HUMAN_SURFACES) {
+            log.info('attach.quotaExceeded', `active=${viewers.size()} cap=${MAX_HUMAN_SURFACES}`);
+            return `browser_webrtc_attach: viewer limit reached (max ${MAX_HUMAN_SURFACES})`;
+        }
+        const routable = canAddressViewer(ctx.ws, ctx.viewerId);
+        const viewer = viewers.attach(ctx.viewerId, ctx.ws, tabId, attachId, { routable });
+        logAttachCreated(viewer);
+        await flushIceConfig(host);
+        noteSessionArmed(viewer.sessionId);
+        await host.startCapture(viewer.sessionId, tabId);
+        if (viewers.getBySession(viewer.sessionId) !== viewer) {
+            log.info('attach.superseded', `session=${viewer.sessionId.slice(0, 8)} — detached while its capture was starting; releasing it`);
+            await host.closeCaptureFor(viewer.sessionId);
+        }
+        return null;
+    },
+    browser_agent_task: async (host, data, ctx) => {
+        const task = extractAgentTask(data);
+        if (!task)
+            return 'browser_agent_task: requires { task: string }';
+        startReasoningAgent(host, ctx.sink, ctx.ws, task, ctx.viewerId);
+        return null;
+    },
+    browser_agent_approve: async (_host, data) => {
+        const payload = extractAgentApprove(data);
+        if (!payload)
+            return 'browser_agent_approve: requires { proposalId, verdict }';
+        return resolveProposal(payload)
+            ? null
+            : `browser_agent_approve: no pending proposal ${payload.proposalId}`;
+    },
+};
+async function handleLeaseRelease(host, sink, ws, data, viewerId) {
+    const req = extractLeaseReleaseRequest(data);
+    if (!req) {
+        sendError(sink, ws, viewerId, 'browser_lease_release: requires { tabId, agentId }');
+        return;
+    }
+    const result = await host.releaseTab(req);
+    log.info('lease.release', `tab=${req.tabId.slice(0, 8)} agent=${req.agentId.slice(0, 20)} released=${result.released}`);
+    if (!result.released)
+        return;
+    let owner = null;
+    try {
+        const driverState = getBrowserDriverState();
+        owner = driverState.getOwner(req.tabId);
+        driverState.clearOwner(req.tabId);
+    }
+    catch (err) {
+        captureException(err, { context: 'websocket.browser.lease_release.clearOwner' });
+    }
+    const attributed = owner?.ownerAgentId === req.agentId ? owner : null;
+    await broadcastAgentTabState(host, sink, req.agentId, attributed?.ownerAgentLabel ?? req.agentId, attributed?.ownerSessionId ? { sessionId: attributed.ownerSessionId } : {});
+}
+export async function handleBrowserHostMessage(host, ws, msg, permission, sink, viewerId) {
+    if (permission === 'view') {
+        const owned = msg.type === 'browser_lease_release' || msg.type in DISPATCH;
+        if (owned && msg.type !== 'browser_input')
+            log('handle.drop', `type=${msg.type} reason=view_only`);
+        return owned;
+    }
+    const sender = viewerId ?? ensureWsViewerId(ws);
+    if (msg.type === 'browser_lease_release') {
+        await runLeaseRelease(host, sink, ws, msg, sender);
+        return true;
+    }
+    const handler = DISPATCH[msg.type];
+    if (!handler)
+        return false;
+    await runDispatch(handler, host, sink, ws, msg, sender);
+    return true;
+}
+function ensureWsViewerId(ws) {
+    if (!ws._viewerId)
+        ws._viewerId = randomUUID();
+    return ws._viewerId;
+}
+async function runLeaseRelease(host, sink, ws, msg, viewerId) {
+    try {
+        await handleLeaseRelease(host, sink, ws, msg.data, viewerId);
+    }
+    catch (err) {
+        log.error('lease.release.threw', err);
+        captureException(err, { context: 'websocket.browser.lease_release' });
+        sendError(sink, ws, viewerId, err instanceof Error ? err.message : String(err));
+    }
+}
+function sendInputRejected(sink, ws, viewerId, payload) {
+    sink.send(ws, addressToViewer({ type: 'browser_input_rejected', data: payload }, ws, viewerId));
+}
+function wireTabIdOf(msg) {
+    return typeof msg.tabId === 'string' && msg.tabId.length > 0 ? msg.tabId : undefined;
+}
+function logInboundBrowserMessage(msg, viewerId) {
+    if (msg.type !== 'browser_input') {
+        log('handle', `type=${msg.type} viewer=${viewerId.slice(0, 8)}`);
+        return;
+    }
+    const d = msg.data;
+    const kind = d?.kind;
+    if (kind === 'key' || kind === 'text' || kind === 'ime') {
+        log('handle.input', `kind=${kind} eventType=${d?.eventType ?? '-'} key=${d?.key ?? '-'} code=${d?.code ?? '-'} tabId=${msg.tabId ?? '-'}`);
+    }
+}
+function handleDispatchThrow(err, sink, ws, msg, viewerId) {
+    log.error('handle.throw', `type=${msg.type} err=${err instanceof Error ? err.message : String(err)}`);
+    captureException(err, { context: `websocket.browser.${msg.type}` });
+    if (msg.type === 'browser_input') {
+        const tabId = wireTabIdOf(msg);
+        sendInputRejected(sink, ws, viewerId, {
+            kind: 'unknown',
+            reason: 'host_not_ready',
+            message: err instanceof Error ? err.message : String(err),
+            ...(tabId ? { tabId } : {}),
+        });
+        return;
+    }
+    sendError(sink, ws, viewerId, err instanceof Error ? err.message : String(err));
+}
+async function runDispatch(handler, host, sink, ws, msg, viewerId) {
+    logInboundBrowserMessage(msg, viewerId);
+    const startedAt = Date.now();
+    const wireTabId = wireTabIdOf(msg);
+    try {
+        const result = await handler(host, msg.data, { ws, viewerId, sink, ...(wireTabId ? { wireTabId } : {}) });
+        if (result === null) {
+            if (msg.type !== 'browser_input')
+                log('handle.ok', `type=${msg.type} ms=${Date.now() - startedAt}`);
+            return;
+        }
+        if (isInputRejection(result)) {
+            log.warn('handle.input_rejected', `type=${msg.type} reason=${result.reason} kind=${result.inputKind}`);
+            sendInputRejected(sink, ws, viewerId, {
+                kind: result.inputKind,
+                reason: result.reason,
+                message: result.message,
+                ...(wireTabId ? { tabId: wireTabId } : {}),
+            });
+            return;
+        }
+        log.info('handle.error', `type=${msg.type} message=${result}`);
+        sendError(sink, ws, viewerId, result);
+    }
+    catch (err) {
+        handleDispatchThrow(err, sink, ws, msg, viewerId);
+    }
+}
+function sendError(sink, ws, viewerId, message) {
+    sink.send(ws, addressToViewer({ type: 'browser_error', data: { code: 'browser_dispatch_error', message } }, ws, viewerId));
+}

package/dist/server/services/websocket/browser-host-broadcast.js

@@ -0,0 +1,179 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { browserLog } from '../browser/debug-log.js';
+import { getBrowserDriverState } from '../browser/driver-state.js';
+import { defaultFormFactor, ensureTabProfileCaptured, isCapturableUrl } from './browser-device-profile.js';
+import { resetSessionState } from './browser-viewer-lifecycle.js';
+import { viewers } from './browser-viewer-registry.js';
+const log = browserLog('handlers');
+export function attachBrowserHostBroadcast(host, sink) {
+    let rosterIds = new Set();
+    const onStatus = (snapshot) => broadcastStatus(sink, snapshot);
+    const onSignal = (envelope) => unicastSignal(sink, envelope);
+    const onTabs = (payload) => {
+        rosterIds = broadcastTabs(host, sink, payload, rosterIds);
+    };
+    const onInputFocus = (event) => unicastInputFocus(host, sink, event);
+    host.on('status', onStatus);
+    host.on('signal', onSignal);
+    host.on('tabs', onTabs);
+    host.on('inputFocus', onInputFocus);
+    return () => {
+        host.off('status', onStatus);
+        host.off('signal', onSignal);
+        host.off('tabs', onTabs);
+        host.off('inputFocus', onInputFocus);
+        closeDriverStateFor(rosterIds);
+        rosterIds = new Set();
+    };
+}
+function broadcastStatus(sink, snapshot) {
+    log.info('broadcast.status', `state=${snapshot.state}${snapshot.reason ? ` reason=${snapshot.reason}` : ''}`);
+    if (snapshot.state === 'stopped' || snapshot.state === 'crashed') {
+        const reason = snapshot.state === 'crashed' ? 'host_crashed' : 'host_stopped';
+        log.info('broadcast.session_reset', `reason=${reason} viewers=${viewers.size()} — clearing session state`);
+        sink.broadcastToAll({ type: 'browser_session_reset', data: { reason } });
+        resetSessionState(reason);
+    }
+    sink.broadcastToAll({ type: 'browser_status', data: snapshot });
+}
+function broadcastTabs(host, sink, payload, previousIds) {
+    log('broadcast.tabs', `count=${payload.tabs.length} current=${payload.currentTabId?.slice(0, 8) ?? 'null'} tabs=[${summarizeTabs(payload.tabs)}]`);
+    sink.broadcastToAll({
+        type: 'browser_state_update',
+        data: { tabs: payload.tabs, currentTabId: payload.currentTabId },
+    });
+    const currentIds = new Set(payload.tabs.map((tab) => tab.id));
+    closeDriverStateFor([...previousIds].filter((id) => !currentIds.has(id)));
+    for (const tab of payload.tabs) {
+        if (tab.deviceProfile || !isCapturableUrl(tab.url))
+            continue;
+        void ensureTabProfileCaptured(host, tab.id, defaultFormFactor()).catch((err) => {
+            log.warn('autoCaptureProfile.failed', `tab=${tab.id.slice(0, 8)} ${String(err)}`);
+        });
+    }
+    return currentIds;
+}
+function closeDriverStateFor(tabIds) {
+    for (const id of tabIds)
+        getBrowserDriverState().closeTab(id);
+}
+function summarizeTabs(tabs) {
+    return tabs
+        .map((tab) => {
+        let where = tab.url || '-';
+        try {
+            where = new URL(tab.url).host || tab.url;
+        }
+        catch {
+        }
+        return `${tab.id.slice(0, 8)}:${where}${tab.isLoading ? ':loading' : ''}`;
+    })
+        .join(',');
+}
+function sendToViewer(sink, viewer, response) {
+    if (!viewer.ws)
+        return;
+    if (viewer.routable)
+        response._target = viewer.viewerId;
+    sink.send(viewer.ws, response);
+}
+function unicastSignal(sink, envelope) {
+    log('signal.in', `kind=${envelope.kind} session=${envelope.sessionId.slice(0, 8)}`);
+    const viewer = viewers.getBySession(envelope.sessionId);
+    if (!viewer) {
+        logUnknownViewerSignal(envelope);
+        return;
+    }
+    if (envelope.kind === 'state')
+        viewer.lastState = envelope.state;
+    logOutboundSignal(envelope, viewer);
+    if (viewer.sdkSink) {
+        viewer.sdkSink({ kind: 'signal', envelope });
+        return;
+    }
+    const response = signalToResponse(envelope, viewer.attachId);
+    if (response)
+        sendToViewer(sink, viewer, response);
+}
+function unicastInputFocus(host, sink, event) {
+    const viewer = viewers.getBySession(event.sessionId);
+    if (!viewer) {
+        log.warn('inputFocus.unknownViewer', `session=${event.sessionId.slice(0, 8)} focused=${event.focused}`);
+        return;
+    }
+    const tabId = event.tabId ?? viewer.tabId;
+    log('broadcast.inputFocus', `session=${event.sessionId.slice(0, 8)} tab=${tabId.slice(0, 8)} focused=${event.focused}`);
+    if (host.getTabInfo(tabId))
+        getBrowserDriverState().recordEditableFocus(tabId, event.focused);
+    if (tabId !== viewer.tabId)
+        return;
+    if (viewer.sdkSink) {
+        viewer.sdkSink({ kind: 'inputFocus', focused: event.focused });
+        return;
+    }
+    sendToViewer(sink, viewer, { type: 'browser_input_focus', data: { focused: event.focused } });
+}
+function signalToResponse(envelope, attachId) {
+    switch (envelope.kind) {
+        case 'offer':
+            return {
+                type: 'browser_webrtc_offer',
+                data: {
+                    sessionId: envelope.sessionId,
+                    sdp: envelope.sdp,
+                    sdpType: 'offer',
+                    ...(attachId ? { attachId } : {}),
+                },
+            };
+        case 'ice':
+            return {
+                type: 'browser_webrtc_ice',
+                data: { sessionId: envelope.sessionId, candidate: envelope.candidate },
+            };
+        case 'state':
+            return {
+                type: 'browser_webrtc_state',
+                data: {
+                    sessionId: envelope.sessionId,
+                    state: envelope.state,
+                    reason: envelope.reason,
+                    ...(envelope.selectedCandidateType !== undefined
+                        ? { selectedCandidateType: envelope.selectedCandidateType }
+                        : {}),
+                },
+            };
+        case 'answer':
+            return null;
+    }
+}
+function logOutboundSignal(envelope, viewer) {
+    const to = viewer.sdkSink ? 'sdk' : viewer.routable ? viewer.viewerId.slice(0, 8) : 'untargeted';
+    const session = envelope.sessionId.slice(0, 8);
+    if (envelope.kind === 'offer') {
+        log.info('signal.offer', `session=${session} attach=${viewer.attachId?.slice(0, 8) ?? '-'} sdpLen=${envelope.sdp.length} to=${to}`);
+    }
+    else if (envelope.kind === 'state') {
+        const path = envelope.selectedCandidateType ? ` path=${envelope.selectedCandidateType}` : '';
+        log.info('signal.state', `session=${session} state=${envelope.state} reason=${envelope.reason ?? '-'}${path} to=${to}`);
+    }
+    else if (envelope.kind === 'ice') {
+        log('signal.ice', `session=${session} ${describeCandidate(envelope.candidate)} to=${to}`);
+    }
+}
+function describeCandidate(candidate) {
+    if (candidate === null || candidate === undefined)
+        return 'eoc';
+    const line = candidate.candidate;
+    if (typeof line !== 'string')
+        return 'typ=?';
+    return `typ=${/ typ (\w+)/.exec(line)?.[1] ?? '?'}`;
+}
+function logUnknownViewerSignal(envelope) {
+    const session = envelope.sessionId.slice(0, 8);
+    if (envelope.kind === 'ice') {
+        log.warn('signal.unknownViewer', `session=${session} kind=ice`);
+        return;
+    }
+    log.error('signal.unknownViewer', `session=${session} kind=${envelope.kind} — dropped: no viewer holds this session (detached or replaced before the host answered)`);
+}

package/dist/server/services/websocket/browser-ice-config.js

@@ -0,0 +1,121 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { browserLog } from '../browser/debug-log.js';
+import { fetchTurnCredentials } from '../platform.js';
+import { captureException } from '../sentry.js';
+import { viewers } from './browser-viewer-registry.js';
+const log = browserLog('handlers');
+const TURN_REFRESH_MARGIN_MS = 30_000;
+let bufferedIceServers = null;
+let iceServersApplied = false;
+const turnlessSessions = new Set();
+let turnCredentialsExpiresAt = 0;
+let turnFetchInFlight = null;
+export function _resetIceConfigForTests() {
+    bufferedIceServers = null;
+    iceServersApplied = false;
+    turnlessSessions.clear();
+    turnCredentialsExpiresAt = 0;
+    turnFetchInFlight = null;
+}
+export function resetIceConfigForHostRestart() {
+    iceServersApplied = false;
+    turnlessSessions.clear();
+}
+export function describeIceConfig() {
+    if (iceServersApplied)
+        return 'applied';
+    return bufferedIceServers ? 'buffered' : 'none';
+}
+export function getAppliedIceServers() {
+    return iceServersApplied ? bufferedIceServers : null;
+}
+export function noteSessionArmed(sessionId) {
+    if (!iceServersApplied)
+        turnlessSessions.add(sessionId);
+}
+export async function applyIceConfig(host, iceServers) {
+    bufferedIceServers = iceServers;
+    const hostState = host.getStatus().state;
+    log.info('iceConfig.apply', `servers=${iceServers.length} hostState=${hostState}${hostState === 'ready' ? '' : ' — buffered until ready'}`);
+    if (hostState !== 'ready')
+        return;
+    try {
+        await host.setIceConfig(iceServers);
+        iceServersApplied = true;
+    }
+    catch (err) {
+        log.error('iceConfig.setFailed', err);
+        captureException(err, { context: 'websocket.browser.setIceConfig' });
+        return;
+    }
+    await healTurnlessViewers(host);
+}
+async function healTurnlessViewers(host) {
+    if (turnlessSessions.size === 0)
+        return;
+    const pending = [...turnlessSessions];
+    turnlessSessions.clear();
+    for (const sessionId of pending) {
+        const viewer = viewers.getBySession(sessionId);
+        if (!viewer)
+            continue;
+        if (viewer.lastState === 'connected' || viewer.lastState === 'closed')
+            continue;
+        log.info('iceConfig.healTurnless', `session=${sessionId.slice(0, 8)} lastState=${viewer.lastState ?? 'pending'} — re-arming with TURN servers`);
+        try {
+            await host.closeCaptureFor(sessionId);
+            await host.startCapture(sessionId, viewer.tabId);
+        }
+        catch (err) {
+            turnlessSessions.add(sessionId);
+            log.error('iceConfig.healTurnless.failed', `session=${sessionId.slice(0, 8)} ${err instanceof Error ? err.message : String(err)}`);
+            captureException(err, { context: 'websocket.browser.healTurnlessViewers' });
+        }
+    }
+}
+export async function flushIceConfig(host) {
+    if (iceServersApplied)
+        return;
+    if (!bufferedIceServers) {
+        log('iceConfig.flush', 'nothing buffered — this capture arms without TURN servers');
+        return;
+    }
+    try {
+        await host.setIceConfig(bufferedIceServers);
+        iceServersApplied = true;
+        log('iceConfig.flushed', `servers=${bufferedIceServers.length}`);
+    }
+    catch (err) {
+        log.error('iceConfig.flushFailed', err);
+        captureException(err, { context: 'websocket.browser.flushIceConfig' });
+    }
+}
+export async function ensureTurnCredentials(host) {
+    if (Date.now() < turnCredentialsExpiresAt - TURN_REFRESH_MARGIN_MS) {
+        log('turn.cached', `applied=${iceServersApplied}`);
+        await flushIceConfig(host);
+        return;
+    }
+    if (turnFetchInFlight)
+        return turnFetchInFlight;
+    turnFetchInFlight = (async () => {
+        try {
+            const result = await fetchTurnCredentials();
+            if (!result) {
+                log.info('turn.unavailable', 'no TURN credentials (not logged in or the fetch failed) — keeping the current ICE config');
+                return;
+            }
+            log('turn.fetched', `servers=${result.iceServers.length} ttl=${result.ttl}s`);
+            turnCredentialsExpiresAt = Date.now() + result.ttl * 1000;
+            await applyIceConfig(host, result.iceServers);
+        }
+        catch (err) {
+            captureException(err, { context: 'websocket.browser.ensureTurnCredentials' });
+        }
+        finally {
+            turnFetchInFlight = null;
+        }
+    })();
+    return turnFetchInFlight;
+}