Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Dedicated Socket.IO namespace for FableLoom QR-hosted play sessions (#5383).
*
* Scoped to `/fableloom-hosted`. A guest connection authenticated with a
* single-use QR token can ONLY access its designated session room and never
* acquires general PortOS auth privileges or access to other socket events.
*/
import { SOCKET_MEDIA_MAX_BYTES } from '../lib/socketPayloadLimits.js';
import { hostedPlaybackUpdateSchema, hostedSpeechDoneSchema, hostedTextTurnSchema } from '../lib/fableLoomValidation.js';
import {
_getInternalSession,
abortHostedTurn,
acknowledgeHostedSpeech,
endHostedSession,
getHostedSession,
processHostedUtterance,
releaseHostedSpeechOutput,
sanitizeHostedSession,
startHostedListening,
switchHostedEpisode,
updateHostedSession,
verifyHostedHostToken,
verifyHostedToken,
} from '../services/fableLoom/hostedSession.js';
// Guest mic payload caps. This socket is authenticated by a single-use QR token
// from a guest device, not by the install's one trusted user, so the root trust
// model does not cover it and the numbers mirror the trusted call path in
// `voice.js` (`MAX_CALL_FRAME_BYTES` / `MAX_AUDIO_BYTES`): one 64 KB frame is
// two seconds of headroom over the ~20 ms bursts the audience page ships, and
// 8 MB is ~4 minutes of 16 kHz mono audio for a single turn.
const MAX_MIC_FRAME_BYTES = 64 * 1024;
const MAX_UTTERANCE_BYTES = SOCKET_MEDIA_MAX_BYTES;
const AUDIO_TOO_LARGE = Symbol('audio-too-large');
// Socket payloads are untrusted: never let Buffer.from coerce arbitrary objects
// or allocate from a declared array-like length. Views represent raw audio bytes,
// including their offsets, rather than an array of numeric sample values.
function boundedAudioBuffer(chunk, maxBytes) {
try {
if (!(chunk instanceof ArrayBuffer) && !ArrayBuffer.isView(chunk)) return null;
if (chunk.byteLength > maxBytes) return AUDIO_TOO_LARGE;
if (Buffer.isBuffer(chunk)) return chunk;
return chunk instanceof ArrayBuffer
? Buffer.from(chunk)
: Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
} catch {
// A detached buffer (or otherwise unusable binary view) is a dropped frame,
// never an exception escaping the Socket.IO event boundary.
return null;
}
}
let hostedNsInstance = null;
export function getHostedNamespace() {
return hostedNsInstance;
}
export function registerFableLoomHostedNamespace(io) {
if (!io || typeof io.of !== 'function') return null;
const ns = io.of('/fableloom-hosted');
hostedNsInstance = ns;
// `io.use(socketAuthGate)` only covers the default namespace, so every role
// here must authenticate with this session's join token.
ns.use(async (socket, next) => {
try {
const auth = socket.handshake.auth || {};
const query = socket.handshake.query || {};
const sessionId = auth.sessionId || query.sessionId;
const token = auth.token || query.token;
const role = auth.role || query.role || 'audience';
if (!sessionId || typeof sessionId !== 'string') {
return next(new Error('SESSION_ID_REQUIRED'));
}
const session = _getInternalSession(sessionId);
if (!session || session.status !== 'active') {
return next(new Error('HOSTED_SESSION_NOT_FOUND_OR_EXPIRED'));
}
if (role !== 'audience' && role !== 'host') {
return next(new Error('HOSTED_SESSION_ROLE_INVALID'));
}
// The audience (QR/join link) token and the host token are distinct
// secrets (#8357) — each role verifies against its own token so the
// audience token can never authenticate a `role: 'host'` connection.
const tokenValid = role === 'host'
? verifyHostedHostToken(sessionId, token)
: verifyHostedToken(sessionId, token);
if (!token || !tokenValid) {
return next(new Error('HOSTED_SESSION_UNAUTHORIZED'));
}
socket.hostedRole = role;
socket.hostedSessionId = sessionId;
return next();
} catch (err) {
return next(new Error(`AUTH_ERROR: ${err?.message || err}`));
}
});
ns.on('connection', (socket) => {
const { hostedSessionId: sessionId, hostedRole: role } = socket;
const room = `session:${sessionId}`;
socket.join(room);
const session = _getInternalSession(sessionId);
if (!session) {
socket.disconnect(true);
return;
}
if (role === 'host') {
session.hostSocketId = socket.id;
} else if (role === 'audience') {
// Single audience device policy: if an existing audience socket was connected, notify/replace
if (session.audienceSocketId && session.audienceSocketId !== socket.id) {
const oldSocket = ns.sockets.get(session.audienceSocketId);
if (oldSocket) {
oldSocket.emit('hosted:session:replaced', { reason: 'Another audience device joined this session.' });
oldSocket.disconnect(true);
}
}
session.audienceSocketId = socket.id;
}
// Emit initial sync snapshot to newly connected client
socket.emit('hosted:session:sync', sanitizeHostedSession(session));
// Broadcast peer connection status to the room
ns.to(room).emit('hosted:peer:status', {
hasHostConnected: !!session.hostSocketId,
hasAudienceConnected: !!session.audienceSocketId,
role,
});
// Inbound frame buffer for streaming mic chunks. `micBytes` is a running
// counter rather than a re-sum of the array, and `micOverflow` latches the
// refusal so an over-cap turn is reported once and never processed as if it
// were a complete utterance.
let micChunks = [];
let micBytes = 0;
let micOverflow = false;
const resetMicBuffer = () => {
micChunks = [];
micBytes = 0;
micOverflow = false;
};
// The record captured at connect goes stale: TTL expiry marks a session
// `ended` without touching `turnPhase`, so a closure gated on that snapshot
// reads `listening` forever. `_getInternalSession` re-evaluates the TTL and
// returns null for a dead session.
const liveSession = () => _getInternalSession(sessionId);
// --- Host actions ---
socket.on('hosted:playback:update', async (data) => {
if (socket.hostedRole !== 'host') return;
try {
const parsed = hostedPlaybackUpdateSchema.safeParse(data);
if (!parsed.success) {
socket.emit('hosted:error', {
code: 'VALIDATION_ERROR',
message: parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '),
});
return;
}
const updated = await updateHostedSession(sessionId, {
playbackPhase: parsed.data.phase,
activeHoldIndex: parsed.data.activeHoldIndex,
currentNodeId: parsed.data.nodeId,
}, { io });
ns.to(room).emit('hosted:playback:sync', {
phase: updated.playbackPhase,
activeHoldIndex: updated.activeHoldIndex,
nodeId: updated.currentNodeId,
});
} catch (err) {
socket.emit('hosted:error', { code: err.code || 'UPDATE_FAILED', message: err.message });
}
});
socket.on('hosted:audio:target', async (data) => {
if (socket.hostedRole !== 'host') return;
try {
const updated = await updateHostedSession(sessionId, { audioTarget: data?.target }, { io });
ns.to(room).emit('hosted:audio:target:updated', { audioTarget: updated.audioTarget });
} catch (err) {
socket.emit('hosted:error', { code: 'TARGET_UPDATE_FAILED', message: err.message });
}
});
// Host advanced to a different episode ("Next: Episode N") — re-bind THIS
// hosted session to it rather than letting the server keep resolving
// audience turns against the old episode's graph (#8112). On preflight
// failure `switchHostedEpisode` already ends the session and broadcasts
// `hosted:session:ended` with reason `episode_not_ready`; there is no live
// room left to answer with a second error frame.
socket.on('hosted:episode:switch', async (data) => {
if (socket.hostedRole !== 'host') return;
const episodeId = typeof data?.episodeId === 'string' ? data.episodeId : null;
if (!episodeId) {
socket.emit('hosted:error', { code: 'EPISODE_ID_REQUIRED', message: 'episodeId is required' });
return;
}
try {
await switchHostedEpisode(sessionId, episodeId, { io });
} catch (err) {
socket.emit('hosted:error', { code: err.code || 'EPISODE_SWITCH_FAILED', message: err.message });
}
});
socket.on('hosted:session:end', () => {
if (socket.hostedRole !== 'host') return;
endHostedSession(sessionId, { reason: 'host_ended', io });
});
// --- Audience actions ---
socket.on('hosted:mic:start', async () => {
if (socket.hostedRole !== 'audience') return;
resetMicBuffer();
try {
await startHostedListening(sessionId, { io });
} catch (err) {
socket.emit('hosted:error', { code: err.code || 'MIC_START_FAILED', message: err.message });
}
});
socket.on('hosted:mic:frame', (chunk) => {
if (socket.hostedRole !== 'audience') return;
const live = liveSession();
if (!live || live.turnPhase !== 'listening') return;
// Already refused this turn — keep dropping until the next mic:start.
if (micOverflow || !chunk) return;
const frame = boundedAudioBuffer(chunk, MAX_MIC_FRAME_BYTES);
if (!Buffer.isBuffer(frame)) return;
if (micBytes + frame.length > MAX_UTTERANCE_BYTES) {
micOverflow = true;
micChunks = [];
micBytes = 0;
socket.emit('hosted:error', {
code: 'UTTERANCE_TOO_LARGE',
message: `audio too large (over ${MAX_UTTERANCE_BYTES} bytes)`,
});
return;
}
micChunks.push(frame);
micBytes += frame.length;
});
socket.on('hosted:mic:stop', async (completeBuffer) => {
if (socket.hostedRole !== 'audience') return;
const live = liveSession();
if (!live || live.turnPhase !== 'listening') return;
const overflowed = micOverflow;
let finalAudio = null;
if (!overflowed && completeBuffer != null) {
const complete = boundedAudioBuffer(completeBuffer, MAX_UTTERANCE_BYTES);
if (!Buffer.isBuffer(complete)) {
resetMicBuffer();
socket.emit('hosted:error', {
code: complete === AUDIO_TOO_LARGE ? 'UTTERANCE_TOO_LARGE' : 'INVALID_AUDIO_FRAME',
message: 'audio must be a binary buffer within the utterance limit',
});
return;
}
finalAudio = complete;
} else if (!overflowed && micChunks.length > 0) {
finalAudio = Buffer.concat(micChunks);
}
resetMicBuffer();
// A truncated buffer would hand the LLM half a sentence with no signal,
// so an overflowed turn is refused outright; the error already went out.
if (overflowed) return;
try {
await processHostedUtterance(sessionId, { audioBuffer: finalAudio, io });
} catch (err) {
if (!err?.hostedReported) socket.emit('hosted:error', { code: err.code || 'UTTERANCE_FAILED', message: err.message });
}
});
socket.on('hosted:turn:text', async (data) => {
if (socket.hostedRole !== 'audience') return;
const live = liveSession();
if (!live) return;
try {
const parsed = hostedTextTurnSchema.safeParse(data);
if (!parsed.success) {
const count = typeof data?.text === 'string' ? data.text.length : null;
const maxLength = hostedTextTurnSchema.shape.text.maxLength;
socket.emit('hosted:error', {
code: 'VALIDATION_ERROR',
message: count === null
? 'Text must be a string.'
: `Text has ${count} characters; send between 1 and ${maxLength} characters.`,
count,
maxLength,
});
return;
}
if (live.turnPhase === 'thinking' || live.turnPhase === 'speaking') {
socket.emit('hosted:error', { code: 'TURN_IN_PROGRESS', message: 'A turn is already in progress' });
return;
}
if (live.turnPhase === 'idle') await startHostedListening(sessionId, { io });
await processHostedUtterance(sessionId, { textMessage: parsed.data.text, io });
} catch (err) {
if (!err?.hostedReported) socket.emit('hosted:error', { code: err.code || 'TEXT_FAILED', message: err.message });
}
});
socket.on('hosted:speech:done', (data) => {
const parsed = hostedSpeechDoneSchema.safeParse(data);
if (!parsed.success) return undefined;
// Role and socket id come from the authenticated connection, never from
// the payload, so the other device cannot finish this turn's playback.
return acknowledgeHostedSpeech(sessionId, {
turnId: parsed.data.turnId,
status: parsed.data.status,
role: socket.hostedRole,
socketId: socket.id,
io,
}).catch((err) => {
console.error(`❌ Hosted speech acknowledgement failed: ${err?.message || err}`);
});
});
socket.on('hosted:turn:abort', () => {
abortHostedTurn(sessionId, { reason: 'client_aborted', io });
});
// --- Disconnect lifecycle ---
socket.on('disconnect', () => {
releaseHostedSpeechOutput(sessionId, socket.id, { io });
if (socket.hostedRole === 'host' && session.hostSocketId === socket.id) {
session.hostSocketId = null;
} else if (socket.hostedRole === 'audience' && session.audienceSocketId === socket.id) {
session.audienceSocketId = null;
}
ns.to(room).emit('hosted:peer:status', {
hasHostConnected: !!session.hostSocketId,
hasAudienceConnected: !!session.audienceSocketId,
disconnectedRole: socket.hostedRole,
});
socket.removeAllListeners();
});
});
return ns;
}
export { MAX_MIC_FRAME_BYTES, MAX_UTTERANCE_BYTES };