Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Pairing codes, and the streaming resampler the satellite's microphone needs.
//
// A pairing code is typed by a person off one screen into another, and it buys
// a microphone in a house. Both halves of that sentence show up here: the code
// alphabet exists so nobody mistypes it, and the normalizer exists so the four
// ways people paste it are all the same code.
import { describe, expect, it } from 'vitest';
import { spawn } from 'node:child_process';
import { createServer } from 'node:net';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { generateCode, normalizeCode, CODE_TTL_MINUTES } from '../api/_lib/home/satellites.js';
import { saveIdentity } from '../services/home-satellite/src/pairing.js';
import { newSecret, verifyToken, ROLE, SATELLITE_TOKEN_TTL_SECONDS } from '../services/home-satellite/src/token.js';
import { PcmDownsampler, floatTo16kPcm } from '../src/voice/mic-capture.js';
describe('pairing codes', () => {
it('generates a readable, hyphenated code', () => {
for (let i = 0; i < 200; i += 1) {
const code = generateCode();
expect(code).toMatch(/^[A-Z2-9]{4}-[A-Z2-9]{4}$/);
// The characters people confuse are the ones that turn a working setup
// into "pairing failed", so they are not in the alphabet at all.
expect(code).not.toMatch(/[O0I1L]/);
}
});
it('generates distinct codes', () => {
const codes = new Set(Array.from({ length: 500 }, generateCode));
expect(codes.size).toBe(500);
});
it('accepts every way somebody pastes the same code', () => {
const canonical = normalizeCode('RH23-KSW5');
expect(canonical).toBe('RH23-KSW5');
expect(normalizeCode('rh23ksw5')).toBe(canonical);
expect(normalizeCode(' RH23 KSW5 \n')).toBe(canonical);
expect(normalizeCode('RH23_KSW5')).toBe(canonical);
});
it('rejects a code that is the wrong length or uses excluded characters', () => {
expect(normalizeCode('RH23-KSW')).toBeNull();
expect(normalizeCode('RH23-KSW55')).toBeNull();
expect(normalizeCode('RH23-KSW0')).toBeNull();
expect(normalizeCode('RH23-KSWI')).toBeNull();
expect(normalizeCode('')).toBeNull();
expect(normalizeCode(null)).toBeNull();
});
it('expires in minutes, not hours', () => {
expect(CODE_TTL_MINUTES).toBeLessThanOrEqual(30);
expect(CODE_TTL_MINUTES).toBeGreaterThan(0);
});
});
describe('the streaming resampler', () => {
const tone = (samples, rate, hz) => Float32Array.from({ length: samples }, (_, i) => Math.sin((2 * Math.PI * hz * i) / rate));
it('produces roughly the right number of samples for a 48 kHz device', () => {
const down = new PcmDownsampler(48000);
let produced = 0;
// 128-sample frames, the size an AudioWorklet actually delivers.
for (let i = 0; i < 375; i += 1) produced += down.push(tone(128, 48000, 220).subarray(0)).length;
// One second of 48 kHz audio is 16000 samples at 16 kHz. Allow a frame of
// slack for the sample carried across the final boundary.
expect(produced).toBeGreaterThan(15980);
expect(produced).toBeLessThanOrEqual(16000);
});
it('does not drop a fraction of a sample on every frame', () => {
// 128 samples at 48 kHz is 42.67 output samples. A stateless resample
// floors that 375 times a second, loses 250 samples, and turns a sentence
// into a click track.
const stateless = Math.floor(128 / 3) * 375;
const down = new PcmDownsampler(48000);
let streamed = 0;
for (let i = 0; i < 375; i += 1) streamed += down.push(tone(128, 48000, 220)).length;
expect(streamed).toBeGreaterThan(stateless);
});
it('passes 16 kHz through without resampling loss', () => {
const down = new PcmDownsampler(16000);
const out = down.push(tone(1600, 16000, 300));
expect(out.length).toBeGreaterThan(1590);
expect(out).toBeInstanceOf(Int16Array);
});
it('quantizes to signed 16-bit and clamps', () => {
const down = new PcmDownsampler(16000);
const out = down.push(Float32Array.from({ length: 64 }, () => 2));
for (const sample of out) expect(sample).toBe(32767);
});
it('returns nothing for an empty frame', () => {
expect(new PcmDownsampler(48000).push(new Float32Array(0))).toHaveLength(0);
expect(new PcmDownsampler(48000).push(null)).toHaveLength(0);
});
it('forgets its carried state on reset', () => {
const down = new PcmDownsampler(48000);
down.push(tone(4096, 48000, 220));
down.reset();
expect(down._tail).toHaveLength(0);
expect(down._phase).toBe(0);
});
it('agrees with the one-shot conversion the WAV builder uses', () => {
const samples = tone(48000, 48000, 200);
const oneShot = floatTo16kPcm(samples, 48000);
const down = new PcmDownsampler(48000);
let streamed = 0;
for (let i = 0; i < samples.length; i += 128) streamed += down.push(samples.subarray(i, i + 128)).length;
expect(Math.abs(streamed - oneShot.length)).toBeLessThan(4);
});
});
// The `token` role exists to be run on the machine that is already running the
// satellite, because that is where the identity file is. It used to build the
// whole service to reach the signing key, which bound the Wyoming and viewer
// ports a second time and died with EADDRINUSE in exactly that situation. So
// the test that matters is that it mints while those ports are occupied.
describe('the token role', () => {
it('mints a viewer token while the satellite it belongs to is running', async () => {
const dir = await mkdtemp(join(tmpdir(), 'satellite-token-'));
const identity = {
satellite_id: '00000000-0000-4000-8000-00000000beef',
secret: newSecret(),
name: 'Kitchen display',
agent: { id: 'a', name: 'Ada', avatarUrl: null },
};
await saveIdentity(dir, identity);
// Hold two ports and then tell the child to use exactly those, which is
// what a running satellite does to the machine the token is minted on.
const held = [createServer(), createServer()];
const ports = await Promise.all(held.map((s) => new Promise((resolve, reject) => {
s.once('error', reject);
s.listen(0, '127.0.0.1', () => resolve(s.address().port));
})));
try {
const token = await new Promise((resolve, reject) => {
const child = spawn(process.execPath, ['src/index.js', 'token', '--state-dir', dir], {
cwd: fileURLToPath(new URL('../services/home-satellite', import.meta.url)),
env: { ...process.env, WYOMING_PORT: String(ports[0]), VIEWER_PORT: String(ports[1]) },
});
let out = '';
let err = '';
child.stdout.on('data', (b) => { out += b; });
child.stderr.on('data', (b) => { err += b; });
child.on('close', (code) => (code === 0 ? resolve(out.trim()) : reject(new Error(`exit ${code}: ${err}`))));
});
// Nothing but the token: the documented use is `--token "$(… token)"`.
expect(token.split('\n')).toHaveLength(1);
const check = verifyToken(token, identity.secret);
expect(check.ok).toBe(true);
expect(check.claims.sid).toBe(identity.satellite_id);
expect(check.claims.role).toBe(ROLE.VIEWER);
} finally {
await Promise.all(held.map((s) => new Promise((r) => s.close(r))));
await rm(dir, { recursive: true, force: true });
}
});
it('exits non-zero when the satellite has never been paired', async () => {
const dir = await mkdtemp(join(tmpdir(), 'satellite-token-'));
try {
const code = await new Promise((resolve) => {
const child = spawn(process.execPath, ['src/index.js', 'token', '--state-dir', dir], {
cwd: fileURLToPath(new URL('../services/home-satellite', import.meta.url)),
stdio: 'ignore',
});
child.on('close', resolve);
});
expect(code).toBe(1);
} finally {
await rm(dir, { recursive: true, force: true });
}
});
});
describe('satellite hub token lifetime', () => {
// The hub holds no revocation list, so a retired satellite keeps its room slot
// until its token expires. The lifetime is the revocation window: minutes, not a day.
it('is short enough that revoking a satellite takes effect within the hour', () => {
expect(SATELLITE_TOKEN_TTL_SECONDS).toBeLessThanOrEqual(30 * 60);
});
it('is long enough for the satellite to refresh ahead of expiry', () => {
// server.js refreshes HUB_TOKEN_LEAD_SECONDS (600) before exp, floor 60s.
expect(SATELLITE_TOKEN_TTL_SECONDS).toBeGreaterThan(600 + 60);
});
});