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
import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
registerFableLoomHostedNamespace,
getHostedNamespace,
MAX_MIC_FRAME_BYTES,
MAX_UTTERANCE_BYTES,
} from './fableLoomHosted.js';
import {
_getInternalSession,
_resetHostedSessions,
createHostedSession,
getHostedSession,
} from '../services/fableLoom/hostedSession.js';
import * as records from '../services/fableLoom/records.js';
import * as weave from '../services/fableLoom/weave.js';
import * as networkExposure from '../lib/networkExposure.js';
import * as tts from '../services/voice/tts.js';
import * as stt from '../services/voice/stt.js';
import * as providers from '../services/providers.js';
import * as prompts from '../services/promptService.js';
import * as runner from '../services/runner.js';
import * as toolkitState from '../lib/aiToolkitState.js';
import * as autoFixer from '../services/autoFixer.js';
import * as tuiRunner from '../services/tuiPromptRunner.js';
import { createProviderStatusService } from '../lib/aiToolkit/providerStatus.js';
describe('fableLoomHosted Socket.IO namespace', () => {
const mockLoom = {
id: 'loom-1',
name: 'Story 1',
format: 'prose',
participationMode: 'helper',
episodes: [{
id: 'ep-1',
title: 'Episode 1',
startNodeId: 'node-1',
nodes: [{
id: 'node-1',
title: 'Start',
prose: 'Opening prose',
playbackMode: 'decision',
audienceConnection: 'connected',
protagonistPresence: 'offscreen',
isEnding: false,
playbackAssets: { holdLoopVideoHistoryIds: ['vid-1'] },
transitions: [{ id: 'tr-1', targetNodeId: 'node-2', intent: 'go next', triggers: [] }],
}, {
id: 'node-2',
title: 'Next',
prose: 'Second scene prose',
playbackMode: 'decision',
audienceConnection: 'connected',
protagonistPresence: 'offscreen',
isEnding: false,
playbackAssets: { holdLoopVideoHistoryIds: ['vid-2'] },
transitions: [],
}],
}, {
id: 'ep-2',
title: 'Episode 2',
startNodeId: 'node-ep2-1',
nodes: [{
id: 'node-ep2-1',
title: 'Episode 2 opener',
prose: 'Episode two opening prose',
playbackMode: 'decision',
audienceConnection: 'connected',
protagonistPresence: 'offscreen',
isEnding: false,
transitions: [],
}],
}],
};
let mockIo;
let middleware;
let connectionHandler;
let mockNamespace;
let roomEvents;
/**
* Socket.IO socket double. `listeners` and `emitted` hang off the returned
* object so a test can drive one handler and read that socket's own emissions
* without threading three values around.
*/
const makeSocket = ({ role, sessionId, id = `${role}-sock` }) => {
const listeners = {};
const emitted = [];
return {
id,
hostedRole: role,
hostedSessionId: sessionId,
join: vi.fn(),
emit: vi.fn((event, data) => emitted.push({ event, data })),
on: vi.fn((event, fn) => { listeners[event] = fn; }),
removeAllListeners: vi.fn(),
listeners,
emitted,
};
};
const roomEvent = (event) => roomEvents.find((e) => e.event === event);
beforeEach(() => {
_resetHostedSessions();
vi.restoreAllMocks();
// createHostedSession runs the readiness preflight, which refuses to start
// a session unless the install is serving HTTPS.
vi.spyOn(networkExposure, 'getNetworkExposureStatus').mockReturnValue({
scheme: 'https',
httpsEnabled: true,
bind: { host: '0.0.0.0', port: 5555, audience: 'all-interfaces' },
cert: { mode: 'tailscale', tailscaleHost: 'host-example.example-tailnet.ts.net' },
});
vi.spyOn(records, 'getLoom').mockResolvedValue(mockLoom);
vi.spyOn(tts, 'synthesize').mockResolvedValue({ wav: Buffer.from('mockwav'), latencyMs: 20 });
vi.spyOn(stt, 'transcribe').mockResolvedValue({ text: 'go next', latencyMs: 50 });
roomEvents = [];
mockNamespace = {
sockets: new Map(),
use: vi.fn((fn) => { middleware = fn; }),
on: vi.fn((evt, fn) => {
if (evt === 'connection') connectionHandler = fn;
}),
to: vi.fn((room) => ({
emit: vi.fn((event, data) => {
roomEvents.push({ room, event, data });
}),
})),
};
mockIo = {
of: vi.fn(() => mockNamespace),
};
registerFableLoomHostedNamespace(mockIo);
});
it('registers namespace at /fableloom-hosted', () => {
expect(mockIo.of).toHaveBeenCalledWith('/fableloom-hosted');
expect(getHostedNamespace()).toBe(mockNamespace);
expect(middleware).toBeDefined();
expect(connectionHandler).toBeDefined();
});
describe('audience narrator execution boundary', () => {
const api = { id: 'narrator-api', name: 'Narrator API', type: 'api', enabled: true, defaultModel: 'example-model' };
const cli = { id: 'narrator-cli', name: 'Narrator CLI', type: 'cli', enabled: true };
const tui = { id: 'narrator-tui', name: 'Narrator TUI', type: 'tui', enabled: true };
let selected;
let playStage;
let loom;
let status;
beforeEach(() => {
selected = api;
playStage = {};
loom = structuredClone(mockLoom);
records.getLoom.mockImplementation(async () => loom);
vi.spyOn(providers, 'getActiveProvider').mockImplementation(async () => selected);
vi.spyOn(providers, 'getProviderById').mockImplementation(async id => [api, cli, tui].find(p => p.id === id));
vi.spyOn(providers, 'getAllProviders').mockImplementation(async () => ({ providers: [selected, cli, tui] }));
vi.spyOn(prompts, 'getStage').mockImplementation(() => playStage);
vi.spyOn(prompts, 'buildPrompt').mockResolvedValue('Synthetic audience request');
vi.spyOn(runner, 'createRun').mockResolvedValue({ runId: 'guest-run' });
vi.spyOn(runner, 'patchRunMetadata').mockResolvedValue();
vi.spyOn(runner, 'executeApiRun').mockImplementation(async ({ onData, onComplete }) => {
onData(JSON.stringify({ action: 'stay', narration: 'API narration.' }));
onComplete({ success: true });
});
vi.spyOn(runner, 'executeCliRun').mockImplementation(() => { throw new Error('Forbidden CLI dispatch'); });
vi.spyOn(tuiRunner, 'executeTuiRun').mockImplementation(() => { throw new Error('Forbidden TUI dispatch'); });
// Use the production fallback selector, with persistence/health writes stubbed.
status = createProviderStatusService({ defaultFallbackPriority: [cli.id, tui.id] });
vi.spyOn(status, 'markUnavailable').mockResolvedValue();
vi.spyOn(status, 'getFallbackProvider');
vi.spyOn(toolkitState, 'getAIToolkitInstance').mockReturnValue({ services: { providerStatus: status } });
for (const name of ['noteFallbackStarted', 'noteFallbackHandled', 'noteFallbackFailed', 'escalateProviderFailure']) {
vi.spyOn(autoFixer, name).mockResolvedValue();
}
});
async function guestTurn(input, text = 'go next') {
const { session, token, preflight } = await createHostedSession('loom-1', 'ep-1');
const audience = makeSocket({ role: 'audience', sessionId: session.id });
audience.handshake = { auth: { role: 'audience', sessionId: session.id, token } };
const next = vi.fn();
await middleware(audience, next);
expect(next).toHaveBeenCalledWith();
connectionHandler(audience);
await audience.listeners['hosted:mic:start']();
if (input === 'audio') await audience.listeners['hosted:mic:stop'](Buffer.from('synthetic audio'));
else await audience.listeners['hosted:turn:text']({ text, callerPolicy: 'any-text', providerId: cli.id });
expect(runner.executeCliRun).not.toHaveBeenCalled();
expect(tuiRunner.executeTuiRun).not.toHaveBeenCalled();
return { preflight, session: getHostedSession(session.id) };
}
it.each([
['play', 'text', cli], ['stage', 'audio', tui], ['active', 'text', tui],
])('refuses %s process pins through authenticated %s turns', async (pin, input, provider) => {
if (pin === 'play') loom.playSettings = { providerId: provider.id };
if (pin === 'stage') playStage = { provider: provider.id };
if (pin === 'active') selected = provider;
const { preflight, session } = await guestTurn(input);
expect(preflight.checks.llm).toMatchObject({ ok: false, code: 'PROVIDER_MODE_NOT_PERMITTED' });
expect(session.transcript.at(-1).text).toBe('Opening prose');
expect(runner.createRun).not.toHaveBeenCalled();
expect(runner.executeApiRun).not.toHaveBeenCalled();
if (input === 'audio') expect(stt.transcribe).toHaveBeenCalled();
});
it.each(['text', 'audio'])('narrates %s with an API and carries the policy into proactive selection', async input => {
const { preflight, session } = await guestTurn(input);
expect(preflight.checks.llm.ok).toBe(true);
expect(session.transcript.at(-1).text).toBe('API narration.');
expect(runner.createRun).toHaveBeenCalledWith(expect.objectContaining({
requestCapabilities: expect.objectContaining({ allowedModes: ['api'] }),
}));
expect(runner.executeApiRun).toHaveBeenCalledTimes(1);
});
it('preserves the full accepted guest text through the real play prompt boundary', async () => {
const text = ` ${'x'.repeat(996)} `;
const { session } = await guestTurn('text', text);
expect(prompts.buildPrompt).toHaveBeenCalledWith('fableloom-play-turn', expect.objectContaining({ readerMessage: text }));
expect(session.transcript.find((item) => item.role === 'audience')?.text).toBe(text);
});
it('refuses proactive process substitution and retains authored narration', async () => {
selected = { ...api, fallbackProvider: cli.id };
runner.createRun.mockImplementation(async ({ requestCapabilities }) => {
const fallback = status.getFallbackProvider(selected.id, { [selected.id]: selected, [cli.id]: cli, [tui.id]: tui }, null, null, requestCapabilities);
if (!fallback) throw new Error('No eligible narrator fallback');
return { runId: 'fallback-run', provider: fallback.provider };
});
const { session } = await guestTurn('text');
expect(session.transcript.at(-1).text).toBe('Opening prose');
expect(runner.executeApiRun).not.toHaveBeenCalled();
});
it('keeps API failure recovery off configured and priority process fallbacks', async () => {
selected = { ...api, fallbackProvider: cli.id };
runner.executeApiRun.mockImplementation(async ({ onComplete }) => onComplete({ success: false, error: 'Synthetic narrator unavailable' }));
const { session } = await guestTurn('audio');
expect(session.transcript.at(-1).text).toBe('Opening prose');
expect(status.getFallbackProvider).toHaveBeenCalledWith(selected.id, expect.any(Object), null, null,
expect.objectContaining({ allowedModes: ['api'] }));
});
it('preserves process narration for operator play calls without the guest policy', async () => {
selected = cli;
runner.executeCliRun.mockImplementation(async ({ onData, onComplete }) => {
onData(JSON.stringify({ action: 'stay', narration: 'Operator narration.' }));
onComplete({ success: true });
});
const result = await weave.playTurn('loom-1', 'ep-1', { nodeId: 'node-1', message: 'go next' });
expect(result.narration).toBe('Operator narration.');
expect(runner.executeCliRun).toHaveBeenCalledTimes(1);
expect(runner.createRun.mock.calls[0][0].requestCapabilities).toBeUndefined();
});
it('keeps tapped transitions deterministic with a process narrator configured', async () => {
selected = cli;
const result = await weave.playTurn('loom-1', 'ep-1', { nodeId: 'node-1', transitionId: 'tr-1', callerPolicy: 'direct-api' });
expect(result).toMatchObject({ action: 'move', resolvedBy: 'choice', node: { id: 'node-2' } });
expect(runner.createRun).not.toHaveBeenCalled();
});
});
describe('handshake auth middleware', () => {
it('rejects connection without sessionId', async () => {
const socket = { handshake: { auth: {} } };
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith(expect.any(Error));
expect(next.mock.calls[0][0].message).toBe('SESSION_ID_REQUIRED');
});
it('rejects audience connection with missing/invalid token', async () => {
const { session } = await createHostedSession('loom-1', 'ep-1');
const socket = {
handshake: {
auth: { sessionId: session.id, role: 'audience', token: 'bad-token' },
},
};
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith(expect.any(Error));
expect(next.mock.calls[0][0].message).toBe('HOSTED_SESSION_UNAUTHORIZED');
});
it('allows audience connection with valid token', async () => {
const { session, token } = await createHostedSession('loom-1', 'ep-1');
const socket = {
handshake: {
auth: { sessionId: session.id, role: 'audience', token },
},
};
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith();
expect(socket.hostedRole).toBe('audience');
expect(socket.hostedSessionId).toBe(session.id);
});
it('rejects host connection without a token', async () => {
const { session } = await createHostedSession('loom-1', 'ep-1');
const socket = {
handshake: {
auth: { sessionId: session.id, role: 'host' },
},
};
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith(expect.any(Error));
expect(next.mock.calls[0][0].message).toBe('HOSTED_SESSION_UNAUTHORIZED');
});
it('rejects a host connection using another session\'s host token', async () => {
const { session } = await createHostedSession('loom-1', 'ep-1');
const { hostToken: otherHostToken } = await createHostedSession('loom-1', 'ep-1');
const socket = {
handshake: {
auth: { sessionId: session.id, role: 'host', token: otherHostToken },
},
};
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith(expect.any(Error));
expect(next.mock.calls[0][0].message).toBe('HOSTED_SESSION_UNAUTHORIZED');
});
// #8357: the audience (QR/join link) token must never grant the host
// role — that link is handed to the audience device and can be forwarded.
it('rejects a host connection using the AUDIENCE join token', async () => {
const { session, token } = await createHostedSession('loom-1', 'ep-1');
const socket = {
handshake: {
auth: { sessionId: session.id, role: 'host', token },
},
};
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith(expect.any(Error));
expect(next.mock.calls[0][0].message).toBe('HOSTED_SESSION_UNAUTHORIZED');
});
it('rejects an audience connection using the HOST token', async () => {
const { session, hostToken } = await createHostedSession('loom-1', 'ep-1');
const socket = {
handshake: {
auth: { sessionId: session.id, role: 'audience', token: hostToken },
},
};
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith(expect.any(Error));
expect(next.mock.calls[0][0].message).toBe('HOSTED_SESSION_UNAUTHORIZED');
});
it('allows host connection with its own host token', async () => {
const { session, hostToken } = await createHostedSession('loom-1', 'ep-1');
const socket = {
handshake: {
auth: { sessionId: session.id, role: 'host', token: hostToken },
},
};
const next = vi.fn();
await middleware(socket, next);
expect(next).toHaveBeenCalledWith();
expect(socket.hostedRole).toBe('host');
expect(socket.hostedSessionId).toBe(session.id);
});
});
describe('socket event exchange', () => {
let session;
let token;
let hostToken;
let audience;
/** Connect a second, host-role socket into the same session room. */
const connectHost = () => {
const host = makeSocket({ role: 'host', sessionId: session.id });
connectionHandler(host);
roomEvents.length = 0;
return host;
};
beforeEach(async () => {
({ session, token, hostToken } = await createHostedSession('loom-1', 'ep-1'));
// The LLM turn is stubbed by default so utterance tests assert the
// session state machine, not provider behaviour. Tests that care about
// the outcome override this.
vi.spyOn(weave, 'playTurn').mockResolvedValue({
action: 'stay',
narration: 'Nothing changes.',
node: { id: 'node-1' },
ended: false,
});
audience = makeSocket({ role: 'audience', sessionId: session.id });
connectionHandler(audience);
roomEvents.length = 0;
});
it('emits a sanitized session snapshot on connection', () => {
expect(audience.join).toHaveBeenCalledWith(`session:${session.id}`);
const sync = audience.emitted.find((e) => e.event === 'hosted:session:sync');
expect(sync).toBeDefined();
expect(sync.data).toMatchObject({
id: session.id,
loomId: 'loom-1',
episodeId: 'ep-1',
status: 'active',
currentNodeId: 'node-1',
playbackPhase: 'hold',
turnPhase: 'idle',
hasAudienceConnected: true,
});
// The snapshot must never carry either join credential in either form.
expect(sync.data.hashedToken).toBeUndefined();
expect(sync.data.hashedHostToken).toBeUndefined();
expect(JSON.stringify(sync.data)).not.toContain(token);
expect(JSON.stringify(sync.data)).not.toContain(hostToken);
});
it('ignores audience mic controls from a host socket', async () => {
const host = connectHost();
await host.listeners['hosted:mic:start']();
expect(getHostedSession(session.id).turnPhase).toBe('idle');
});
it('advances to the transition target when the utterance matches its intent', async () => {
weave.playTurn.mockResolvedValue({
action: 'move',
transitionId: 'tr-1',
narration: 'Onward.',
node: { id: 'node-2' },
ended: false,
});
await audience.listeners['hosted:mic:start']();
expect(getHostedSession(session.id).turnPhase).toBe('listening');
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(getHostedSession(session.id).currentNodeId).toBe('node-2');
expect(roomEvent('hosted:story:transition')?.data).toMatchObject({ transitionId: 'tr-1' });
});
it('stays on the current scene when the utterance matches no transition', async () => {
await audience.listeners['hosted:mic:start']();
await audience.listeners['hosted:turn:text']({ text: 'unrelated words' });
const state = getHostedSession(session.id);
expect(state.currentNodeId).toBe('node-1');
expect(state.turnPhase).toBe('listening');
expect(roomEvent('hosted:story:transition')).toBeUndefined();
});
it('reports a failed turn once to the room, then returns every client to idle', async () => {
await audience.listeners['hosted:mic:start']();
records.getLoom.mockRejectedValueOnce(new Error('loom read failed'));
await audience.listeners['hosted:turn:text']({ text: 'go next' });
const errors = roomEvents.filter((e) => e.event === 'hosted:error');
expect(errors).toHaveLength(1);
expect(errors[0].data).toMatchObject({ code: 'TURN_FAILED', message: 'loom read failed' });
expect(audience.emitted.find((e) => e.event === 'hosted:error')).toBeUndefined();
const names = roomEvents.map((e) => e.event);
const phaseAfterError = roomEvents.slice(names.indexOf('hosted:error') + 1)
.find((e) => e.event === 'hosted:turn:phase');
expect(phaseAfterError?.data).toMatchObject({ phase: 'idle' });
expect(getHostedSession(session.id).turnPhase).toBe('idle');
});
it('opens a text turn from the initial idle session without a microphone start', async () => {
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(weave.playTurn).toHaveBeenCalledWith('loom-1', 'ep-1', expect.objectContaining({ message: 'go next' }));
expect(getHostedSession(session.id).currentNodeId).toBe('node-1');
expect(audience.emitted.find((e) => e.event === 'hosted:error')).toBeUndefined();
});
it('opens another typed turn after a scene transition returns the session to idle', async () => {
weave.playTurn.mockResolvedValueOnce({
action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
});
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(getHostedSession(session.id)).toMatchObject({ turnPhase: 'idle', currentNodeId: 'node-2' });
await audience.listeners['hosted:turn:text']({ text: 'look around' });
expect(weave.playTurn).toHaveBeenLastCalledWith('loom-1', 'ep-1', expect.objectContaining({
nodeId: 'node-2', message: 'look around',
}));
expect(weave.playTurn).toHaveBeenCalledTimes(2);
});
it('reports the live gate refusal and permits a new text turn after playback returns to hold', async () => {
const host = connectHost();
await host.listeners['hosted:playback:update']({ phase: 'entry' });
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(audience.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'PLAYBACK_NOT_IN_HOLD_PHASE' });
expect(weave.playTurn).not.toHaveBeenCalled();
expect(getHostedSession(session.id).turnPhase).toBe('idle');
await host.listeners['hosted:playback:update']({ phase: 'hold' });
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(weave.playTurn).toHaveBeenCalledOnce();
});
it.each(['thinking', 'speaking'])('refuses typed turns while %s', async (phase) => {
_getInternalSession(session.id).turnPhase = phase;
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(audience.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'TURN_IN_PROGRESS' });
expect(weave.playTurn).not.toHaveBeenCalled();
expect(getHostedSession(session.id).turnPhase).toBe(phase);
});
it.each(['text', 'mic'])('refuses a concurrent idle %s admission without replacing the first text turn', async (second) => {
let resolveLoom;
records.getLoom.mockImplementationOnce(() => new Promise((resolve) => { resolveLoom = resolve; }));
const pending = audience.listeners['hosted:turn:text']({ text: 'first request' });
if (second === 'text') await audience.listeners['hosted:turn:text']({ text: 'second request' });
else await audience.listeners['hosted:mic:start']();
expect(audience.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'TURN_IN_PROGRESS' });
resolveLoom(mockLoom);
await pending;
expect(weave.playTurn).toHaveBeenCalledOnce();
expect(weave.playTurn).toHaveBeenCalledWith('loom-1', 'ep-1', expect.objectContaining({ message: 'first request' }));
expect(getHostedSession(session.id).transcript.filter((item) => item.role === 'audience'))
.toMatchObject([{ text: 'first request' }]);
});
it('releases text admission after a failed loom read so a retry can succeed', async () => {
records.getLoom.mockRejectedValueOnce(new Error('loom read failed'));
await audience.listeners['hosted:turn:text']({ text: 'first request' });
expect(audience.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'TEXT_FAILED', message: 'loom read failed' });
expect(weave.playTurn).not.toHaveBeenCalled();
await audience.listeners['hosted:turn:text']({ text: 'retry request' });
expect(weave.playTurn).toHaveBeenCalledOnce();
});
it('reports an episode-switch refusal and accepts text after the switch completes', async () => {
const host = connectHost();
let resolveLoom;
records.getLoom.mockImplementationOnce(() => new Promise((resolve) => { resolveLoom = resolve; }));
const pending = host.listeners['hosted:episode:switch']({ episodeId: 'ep-2' });
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(audience.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'EPISODE_SWITCH_IN_PROGRESS' });
expect(weave.playTurn).not.toHaveBeenCalled();
resolveLoom(mockLoom);
await pending;
await audience.listeners['hosted:turn:text']({ text: 'new episode request' });
expect(weave.playTurn).toHaveBeenCalledWith('loom-1', 'ep-2', expect.objectContaining({
nodeId: 'node-ep2-1', message: 'new episode request',
}));
});
it.each([{}, { text: 42 }, { text: { message: 'go next' } }, { text: null }, { text: '' }, { text: 'x'.repeat(1001) }])(
'rejects invalid text payload %# before opening a turn or publishing a transcript', async (payload) => {
await audience.listeners['hosted:turn:text'](payload);
const error = audience.emitted.find((e) => e.event === 'hosted:error')?.data;
expect(error).toMatchObject({ code: 'VALIDATION_ERROR', maxLength: 1000 });
expect(error.count).toBe(typeof payload.text === 'string' ? payload.text.length : null);
if (typeof payload.text === 'string') expect(error.message).toContain(String(payload.text.length));
expect(weave.playTurn).not.toHaveBeenCalled();
expect(getHostedSession(session.id)).toMatchObject({ turnPhase: 'idle' });
expect(getHostedSession(session.id).transcript).toHaveLength(1);
expect(roomEvent('hosted:turn:transcript')).toBeUndefined();
},
);
it('passes a text message at the REST limit through without cutting it', async () => {
const text = 'x'.repeat(1000);
await audience.listeners['hosted:turn:text']({ text });
expect(weave.playTurn).toHaveBeenCalledWith('loom-1', 'ep-1', expect.objectContaining({ message: text }));
expect(roomEvent('hosted:turn:transcript')?.data).toMatchObject({ text });
});
it('buffers mic frames while listening and transcribes them on mic:stop', async () => {
await audience.listeners['hosted:mic:start']();
audience.listeners['hosted:mic:frame'](Buffer.from('aa'));
audience.listeners['hosted:mic:frame'](Buffer.from('bb'));
await audience.listeners['hosted:mic:stop']();
expect(stt.transcribe).toHaveBeenCalledWith(Buffer.from('aabb'), expect.anything());
});
it('drops malformed frames without coercion and keeps the guest session usable', async () => {
// Complete the real admission middleware before exercising the listener.
audience.handshake = { auth: { role: 'audience', sessionId: session.id, token } };
const next = vi.fn();
await middleware(audience, next);
expect(next).toHaveBeenCalledWith();
await audience.listeners['hosted:mic:start']();
const declaredLength = vi.fn(() => { throw new Error('array-like length was read'); });
const arrayLike = { get length() { return declaredLength(); } };
const detached = new ArrayBuffer(8);
structuredClone(detached, { transfer: [detached] });
for (const payload of [{}, 42, 'audio', [1, 2], { type: 'Buffer', data: [1] }, arrayLike, detached]) {
expect(() => audience.listeners['hosted:mic:frame'](payload)).not.toThrow();
}
expect(declaredLength).not.toHaveBeenCalled();
audience.listeners['hosted:mic:frame'](Buffer.from('still usable'));
await audience.listeners['hosted:mic:stop']();
expect(stt.transcribe).toHaveBeenCalledWith(Buffer.from('still usable'), expect.anything());
});
it('preserves raw bytes and slice offsets of binary microphone frames', async () => {
await audience.listeners['hosted:mic:start']();
const bytes = Uint8Array.from([0xff, 0x61, 0x62, 0xff]);
audience.listeners['hosted:mic:frame'](bytes.subarray(1, 3));
audience.listeners['hosted:mic:frame'](new DataView(bytes.buffer, 1, 2));
audience.listeners['hosted:mic:frame'](Uint8Array.from([0x63]).buffer);
audience.listeners['hosted:mic:frame'](new Uint16Array(bytes.buffer, 0, 1));
await audience.listeners['hosted:mic:stop']();
expect(stt.transcribe).toHaveBeenCalledWith(Buffer.from([0x61, 0x62, 0x61, 0x62, 0x63, 0xff, 0x61]), expect.anything());
});
it('stops buffering mic frames once the session expires mid-listen', async () => {
await audience.listeners['hosted:mic:start']();
// TTL expiry marks the record `ended` but never touches `turnPhase`, so a
// handler gated on the connect-time snapshot would still read `listening`
// and keep appending for the whole life of the socket.
const record = _getInternalSession(session.id);
record.expiresAt = new Date(Date.now() - 1000).toISOString();
audience.listeners['hosted:mic:frame'](Buffer.from('aa'));
audience.listeners['hosted:mic:frame'](Buffer.from('bb'));
// Revive the record so mic:stop reaches the buffer it would have filled.
record.expiresAt = new Date(Date.now() + 60_000).toISOString();
record.status = 'active';
await audience.listeners['hosted:mic:stop']();
expect(stt.transcribe).not.toHaveBeenCalled();
});
it('drops a single mic frame larger than the per-frame cap', async () => {
await audience.listeners['hosted:mic:start']();
audience.listeners['hosted:mic:frame'](Buffer.alloc(MAX_MIC_FRAME_BYTES + 1, 0x7a));
audience.listeners['hosted:mic:frame'](new ArrayBuffer(MAX_MIC_FRAME_BYTES + 1));
audience.listeners['hosted:mic:frame'](new Uint16Array(MAX_MIC_FRAME_BYTES / 2 + 1));
audience.listeners['hosted:mic:frame'](Buffer.from('aa'));
await audience.listeners['hosted:mic:stop']();
expect(stt.transcribe).toHaveBeenCalledWith(Buffer.from('aa'), expect.anything());
});
it('refuses the turn once buffered mic frames exceed the utterance cap', async () => {
await audience.listeners['hosted:mic:start']();
const frame = Buffer.alloc(MAX_MIC_FRAME_BYTES, 0x61);
const framesToCap = MAX_UTTERANCE_BYTES / MAX_MIC_FRAME_BYTES;
for (let i = 0; i < framesToCap; i += 1) {
audience.listeners['hosted:mic:frame'](frame);
}
expect(audience.emitted.filter((e) => e.event === 'hosted:error')).toHaveLength(0);
// These two both overflow; the refusal is reported exactly once per turn.
audience.listeners['hosted:mic:frame'](frame);
audience.listeners['hosted:mic:frame'](frame);
const errors = audience.emitted.filter((e) => e.event === 'hosted:error');
expect(errors).toHaveLength(1);
expect(errors[0].data).toMatchObject({ code: 'UTTERANCE_TOO_LARGE' });
await audience.listeners['hosted:mic:stop']();
expect(stt.transcribe).not.toHaveBeenCalled();
});
it('refuses a hosted:mic:stop complete buffer larger than the utterance cap', async () => {
await audience.listeners['hosted:mic:start']();
await audience.listeners['hosted:mic:stop'](Buffer.alloc(MAX_UTTERANCE_BYTES + 1, 0x61));
expect(stt.transcribe).not.toHaveBeenCalled();
expect(audience.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'UTTERANCE_TOO_LARGE' });
});
it('rejects a malformed complete buffer and accepts a subsequent sliced binary utterance', async () => {
await audience.listeners['hosted:mic:start']();
await audience.listeners['hosted:mic:stop']({ length: 2 ** 32 });
expect(stt.transcribe).not.toHaveBeenCalled();
expect(audience.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'INVALID_AUDIO_FRAME' });
await audience.listeners['hosted:mic:start']();
const bytes = Uint8Array.from([0xff, 0x61, 0x62, 0xff]);
await audience.listeners['hosted:mic:stop'](new DataView(bytes.buffer, 1, 2));
expect(stt.transcribe).toHaveBeenCalledWith(Buffer.from('ab'), expect.anything());
});
it('ignores hosted:mic:stop when the session is not listening', async () => {
await audience.listeners['hosted:mic:stop'](Buffer.from('aa'));
expect(stt.transcribe).not.toHaveBeenCalled();
expect(getHostedSession(session.id).turnPhase).toBe('idle');
});
it('lets a host drive hosted:playback:update', async () => {
const host = connectHost();
await host.listeners['hosted:playback:update']({ phase: 'entry', activeHoldIndex: 1, nodeId: 'node-2' });
expect(roomEvent('hosted:playback:sync')?.data).toEqual({
phase: 'entry',
activeHoldIndex: 1,
nodeId: 'node-2',
});
expect(getHostedSession(session.id)).toMatchObject({
playbackPhase: 'entry',
activeHoldIndex: 1,
currentNodeId: 'node-2',
});
});
it('refuses hosted:playback:update from an audience socket', () => {
audience.listeners['hosted:playback:update']({ phase: 'entry', activeHoldIndex: 1, nodeId: 'node-2' });
expect(roomEvent('hosted:playback:sync')).toBeUndefined();
expect(getHostedSession(session.id)).toMatchObject({
playbackPhase: 'hold',
activeHoldIndex: 0,
currentNodeId: 'node-1',
});
});
it.each([
{ phase: 'not-a-phase' }, { activeHoldIndex: -1 }, { activeHoldIndex: 11 },
{ activeHoldIndex: 1.5 }, { activeHoldIndex: '1' }, { nodeId: 42 },
])('rejects playback payload %# outside the REST schema without changing state', async (payload) => {
const host = connectHost();
await host.listeners['hosted:playback:update'](payload);
expect(host.emitted.find((e) => e.event === 'hosted:error')?.data).toMatchObject({ code: 'VALIDATION_ERROR' });
expect(getHostedSession(session.id)).toMatchObject({ playbackPhase: 'hold', activeHoldIndex: 0, currentNodeId: 'node-1' });
expect(roomEvent('hosted:playback:sync')).toBeUndefined();
});
it.each([0, 10])('accepts the REST playback hold-index boundary %s', async (activeHoldIndex) => {
const host = connectHost();
await host.listeners['hosted:playback:update']({ phase: 'hold', activeHoldIndex, nodeId: 'node-2' });
expect(roomEvent('hosted:playback:sync')?.data).toEqual({ phase: 'hold', activeHoldIndex, nodeId: 'node-2' });
});
// #8112: only the host may re-bind this hosted session's episode. An
// audience socket triggering this would let a guest device rewrite the
// story the host is presenting.
it('lets a host switch episodes and re-syncs the room', async () => {
const host = connectHost();
await host.listeners['hosted:episode:switch']({ episodeId: 'ep-2' });
expect(getHostedSession(session.id)).toMatchObject({
episodeId: 'ep-2',
currentNodeId: 'node-ep2-1',
turnPhase: 'idle',
});
const sync = roomEvent('hosted:session:sync');
expect(sync?.data).toMatchObject({ episodeId: 'ep-2', currentNodeId: 'node-ep2-1' });
expect(sync?.data.transcript).toHaveLength(1);
});
it('refuses hosted:episode:switch from an audience socket', async () => {
await audience.listeners['hosted:episode:switch']({ episodeId: 'ep-2' });
expect(getHostedSession(session.id)).toMatchObject({ episodeId: 'ep-1', currentNodeId: 'node-1' });
expect(roomEvent('hosted:session:sync')).toBeUndefined();
});
it('emits hosted:error when hosted:episode:switch is sent with no episodeId', async () => {
const host = connectHost();
await host.listeners['hosted:episode:switch']({});
expect(host.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'EPISODE_ID_REQUIRED' });
expect(getHostedSession(session.id).episodeId).toBe('ep-1');
});
it('emits hosted:error to the host when the target episode does not exist', async () => {
const host = connectHost();
await host.listeners['hosted:episode:switch']({ episodeId: 'no-such-episode' });
expect(host.emitted.find((e) => e.event === 'hosted:error')?.data)
.toMatchObject({ code: 'NOT_FOUND' });
expect(getHostedSession(session.id).episodeId).toBe('ep-1');
});
it('ignores a hosted:speech:done that is not bound to the current turn', () => {
_getInternalSession(session.id).turnPhase = 'speaking';
audience.listeners['hosted:speech:done']({});
audience.listeners['hosted:speech:done']({
turnId: '00000000-0000-4000-8000-000000000000', status: 'ended',
});
expect(getHostedSession(session.id).turnPhase).toBe('speaking');
expect(roomEvent('hosted:turn:phase')).toBeUndefined();
});
it('commits a move only from the designated host output for the current turn', async () => {
const host = connectHost();
weave.playTurn.mockResolvedValue({
action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
});
await audience.listeners['hosted:turn:text']({ text: 'go next' });
const turnId = roomEvent('hosted:turn:tts')?.data?.turnId;
expect(turnId).toEqual(expect.any(String));
expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'speaking' });
expect(roomEvent('hosted:story:transition')).toBeUndefined();
await audience.listeners['hosted:turn:text']({ text: 'overlap' });
expect(audience.emitted.find((event) => event.event === 'hosted:error')?.data)
.toMatchObject({ code: 'TURN_IN_PROGRESS' });
expect(getHostedSession(session.id).currentNodeId).toBe('node-1');
await audience.listeners['hosted:speech:done']({ turnId, status: 'ended' });
await host.listeners['hosted:speech:done']({
turnId: '00000000-0000-4000-8000-000000000000', status: 'ended',
});
expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'speaking' });
await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-2', turnPhase: 'idle' });
expect(roomEvents.filter((event) => event.event === 'hosted:story:transition')).toHaveLength(1);
await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
expect(roomEvents.filter((event) => event.event === 'hosted:story:transition')).toHaveLength(1);
});
it('lets the audience output commit when playback is aimed at the audience', async () => {
_getInternalSession(session.id).audioTarget = 'audience';
const host = connectHost();
weave.playTurn.mockResolvedValue({
action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
});
await audience.listeners['hosted:turn:text']({ text: 'go next' });
const turnId = roomEvent('hosted:turn:tts')?.data?.turnId;
await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
expect(getHostedSession(session.id).currentNodeId).toBe('node-1');
await audience.listeners['hosted:speech:done']({ turnId, status: 'ended' });
expect(getHostedSession(session.id).currentNodeId).toBe('node-2');
});
it('drops a pending move when playback fails or the designated host disconnects', async () => {
const host = connectHost();
weave.playTurn.mockResolvedValue({
action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
});
await audience.listeners['hosted:turn:text']({ text: 'go next' });
const failedTurn = roomEvent('hosted:turn:tts')?.data?.turnId;
await host.listeners['hosted:speech:done']({ turnId: failedTurn, status: 'failed' });
expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'idle' });
expect(roomEvent('hosted:story:transition')).toBeUndefined();
await audience.listeners['hosted:turn:text']({ text: 'go next' });
const turnId = roomEvents.filter((event) => event.event === 'hosted:turn:tts').at(-1)?.data?.turnId;
host.listeners.disconnect();
expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'idle' });
await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
expect(roomEvent('hosted:story:transition')).toBeUndefined();
});
it('commits a text-only turn immediately when synthesis produces no audio', async () => {
connectHost();
tts.synthesize.mockResolvedValueOnce(null);
weave.playTurn.mockResolvedValue({
action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
});
await audience.listeners['hosted:turn:text']({ text: 'go next' });
expect(roomEvent('hosted:turn:tts')).toBeUndefined();
expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-2', turnPhase: 'idle' });
expect(roomEvent('hosted:story:transition')?.data).toMatchObject({ transitionId: 'tr-1' });
});
it('drops the in-flight turn on hosted:turn:abort', async () => {
await audience.listeners['hosted:mic:start']();
roomEvents.length = 0;
audience.listeners['hosted:turn:abort']();
expect(getHostedSession(session.id).turnPhase).toBe('idle');
expect(roomEvent('hosted:turn:phase')?.data).toMatchObject({ phase: 'idle', reason: 'client_aborted' });
expect(roomEvent('hosted:turn:phase')?.data.turnId).toEqual(expect.any(String));
});
it('releases the audience slot and tears down listeners on disconnect', () => {
audience.listeners.disconnect();
expect(audience.removeAllListeners).toHaveBeenCalled();
expect(roomEvent('hosted:peer:status')?.data).toMatchObject({
hasAudienceConnected: false,
disconnectedRole: 'audience',
});
expect(getHostedSession(session.id).hasAudienceConnected).toBe(false);
});
});
});