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
// The pool, against a real Home Assistant.
//
// The pure tests in tests/home-runtime.test.js prove the refcounting, the cap,
// the breaker and the eviction boundary with a fake bridge, because a working
// house cannot be asked to fail its next five connects on cue. What they cannot
// prove is the claim the whole module exists for: that a second call really
// rides the first WebSocket instead of opening another one against somebody's
// instance. That needs a real socket and a real house, so it lives here.
//
// Self-skipping, and it builds its own house. The lane has ONE way to get a
// real Home Assistant, so this file asks for it rather than describing it:
//
// npm run test:home:live
// HOME_LIVE=1 HOME_ALLOW_LOCAL_INSTANCE=1 npx vitest run tests/home-runtime-live.test.js
//
// Pointing at a house you already have still works, via HOME_ASSISTANT_URL and
// HOME_ASSISTANT_TOKEN, because acquireHomeInstance prefers those when set.
//
// HOME_ALLOW_LOCAL_INSTANCE=1 is the seam documented in
// api/_lib/home-url-guard.js, and unlike every other live file in the lane this
// one needs it: the runtime dials the house through the same reachability guard
// the API uses, and a harness instance lands on loopback, which that guard
// refuses. It is part of the gate rather than a hard failure so that a run
// without it skips with a reason instead of reporting the guard as a bug.
//
// Never mocked. A fake instance is what hid Home Assistant's own
// `intent__HassTurnOff` performing an UNLOCK on a lock, which is the single most
// important thing this lane learned.
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import { createHomeRuntime } from '../api/_lib/home/runtime.js';
import { HOME_STATUS } from '../api/_lib/home/store.js';
import { HomeBridge } from '@three-ws/home-bridge';
import { acquireHomeInstance, liveHomeAvailable } from './_helpers/home-instance.js';
// Filled in by beforeAll from the shared harness instance. Every reader below
// runs inside a test, so a late assignment is the whole cost of not making each
// developer hand-build a house first.
let BASE_URL;
let TOKEN;
const live = describe.skipIf(!liveHomeAvailable() || process.env.HOME_ALLOW_LOCAL_INSTANCE !== '1');
const HOME_ID = '44444444-4444-4444-8444-444444444444';
const USER_ID = '55555555-5555-4555-8555-555555555555';
/** Counts the sockets actually constructed, which is the measurement this file exists for. */
function countingFactory() {
const built = [];
const factory = (options) => {
const bridge = new HomeBridge(options);
built.push(bridge);
return bridge;
};
factory.built = built;
return factory;
}
/** The store, reduced to the reads the runtime performs, pointed at the live instance. */
function liveStoreDeps() {
const handshakes = [];
return {
handshakes,
getConnection: async (id, userId) =>
id === HOME_ID && userId === USER_ID
? { id, user_id: userId, label: 'Live', base_url: BASE_URL, status: HOME_STATUS.CONNECTED }
: null,
getDecryptedToken: async () => ({
token: TOKEN,
baseUrl: BASE_URL,
transport: 'direct',
relayId: null,
fingerprint: 'live',
}),
listAllowedEntities: async () => [],
recordHandshake: async (id, update) => {
handshakes.push({ id, ...update });
return null;
},
};
}
const runtimes = [];
function liveRuntime(extra = {}) {
const createBridge = countingFactory();
const deps = liveStoreDeps();
const runtime = createHomeRuntime({ createBridge, ...deps, ...extra });
runtimes.push(runtime);
return { runtime, createBridge, deps };
}
afterAll(() => {
// Leaving a socket open would hold the instance's connection slot after the
// run, which is exactly the failure this module is here to prevent.
for (const runtime of runtimes) runtime.closeAll();
});
live('home runtime, against a real Home Assistant', () => {
beforeAll(async () => {
const instance = await acquireHomeInstance();
BASE_URL = instance.baseUrl;
TOKEN = instance.token;
}, 600_000);
it('opens one socket for two sequential withHome calls', async () => {
const { runtime, createBridge } = liveRuntime();
const first = await runtime.withHome(HOME_ID, USER_ID, (bridge) => ({
rooms: bridge.graph.rooms.length,
entities: Object.keys(bridge.states).length,
version: bridge.haVersion,
}));
const second = await runtime.withHome(HOME_ID, USER_ID, (bridge) => ({
rooms: bridge.graph.rooms.length,
entities: Object.keys(bridge.states).length,
}));
// A real house answered, twice, with the same numbers.
expect(first.entities).toBeGreaterThan(0);
expect(second.entities).toBe(first.entities);
expect(first.rooms).toBe(second.rooms);
expect(first.version).toMatch(/^\d+\.\d+/);
// And it did so over ONE socket. This assertion is the whole file.
expect(createBridge.built).toHaveLength(1);
expect(createBridge.built[0].connected).toBe(true);
expect(runtime.stats().open).toBe(1);
runtime.closeAll();
expect(createBridge.built[0].connected).toBe(false);
}, 60_000);
it('records the handshake it measured, so the store never holds a guessed capability', async () => {
const { runtime, deps } = liveRuntime();
await runtime.withHome(HOME_ID, USER_ID, () => null);
// The handshake write is fire and forget on purpose; give it a turn.
await new Promise((resolve) => setTimeout(resolve, 50));
const recorded = deps.handshakes.find((h) => h.status === HOME_STATUS.CONNECTED);
expect(recorded).toBeTruthy();
expect(recorded.capabilities.websocket).toBe(true);
expect(recorded.capabilities.entityCount).toBeGreaterThan(0);
expect(recorded.capabilities.haVersion).toMatch(/^\d+\.\d+/);
runtime.closeAll();
}, 60_000);
it('reopens after eviction, which is the cold path a recycled instance takes', async () => {
let clock = 1_000_000;
const { runtime, createBridge } = liveRuntime({ now: () => clock, idleMs: 1_000 });
await runtime.withHome(HOME_ID, USER_ID, () => null);
clock += 1_001;
expect(runtime.evictIdle(clock)).toBe(1);
expect(createBridge.built[0].connected).toBe(false);
const rooms = await runtime.withHome(HOME_ID, USER_ID, (bridge) => bridge.graph.rooms.length);
expect(createBridge.built).toHaveLength(2);
expect(rooms).toBeGreaterThanOrEqual(0);
runtime.closeAll();
}, 60_000);
it('holds one socket while a subscriber watches, and releases it when they leave', async () => {
let clock = 1_000_000;
const { runtime, createBridge } = liveRuntime({ now: () => clock, idleMs: 1_000 });
const events = [];
const unsubscribe = await runtime.subscribe(HOME_ID, USER_ID, (event) => events.push(event));
expect(events).toHaveLength(1);
expect(events[0].connected).toBe(true);
expect(events[0].stale).toBe(false);
expect(runtime.stats().subscribers).toBe(1);
// A watched home is never evicted out from under the browser watching it.
clock += 60_000;
expect(runtime.evictIdle(clock)).toBe(0);
unsubscribe();
clock += 1_001;
expect(runtime.evictIdle(clock)).toBe(1);
expect(createBridge.built[0].connected).toBe(false);
}, 60_000);
it('fails a bad token as auth rather than as an unreachable house', async () => {
const createBridge = countingFactory();
const runtime = createHomeRuntime({
createBridge,
...liveStoreDeps(),
getDecryptedToken: async () => ({
token: 'not-a-real-token',
baseUrl: BASE_URL,
transport: 'direct',
relayId: null,
fingerprint: 'bad',
}),
});
runtimes.push(runtime);
// The two failures need different recovery text, so they must not collapse
// into one code: "your house is offline" and "your token is wrong" send the
// user to completely different places.
await expect(runtime.acquire(HOME_ID, USER_ID)).rejects.toMatchObject({ code: 'auth' });
expect(runtime.stats().open).toBe(0);
}, 60_000);
});