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
test(home): prove the over-quota safety exemption against a real house
nirholasef8863b581de
diff --git a/docs/home-plans.md b/docs/home-plans.mdindex ea846b71f..6c69045a3 100644--- a/docs/home-plans.md+++ b/docs/home-plans.md@@ -309,3 +309,48 @@ quota you only meet at the moment it refuses you is a quota nobody showed you.It is also where a user swaps which homes are live after a downgrade, and where the two lines alimit can never touch are stated in words rather than buried in a policy nobody opens.++---++## How the two commitments are verified++Both commitments are covered by tests that drive a real Home Assistant, not by unit tests over our+own classifier. Bring a house up first:++```bash+node scripts/home-test-instance.mjs --up --onboard --seed --name plan19+```++**Commitment 1, the safety exemption.** The live block at the end of+[`tests/home-turn-gate.test.js`](../tests/home-turn-gate.test.js) puts an account past every+dimension at once (an override of `0` on all of them) and pauses its home the way a downgrade+does, then asks the real house to lock a deadbolt, close a cover and arm the alarm. Each one+asserts the state read back out of Home Assistant, so a pass means the device moved. In the same+moment it asserts that an ordinary action and the unsafe direction of a safety domain are both+still refused, because an exemption that is not selective is just a broken gate.++```bash+HOME_LIVE=1 HOME_LIVE_NAME=plan19 HOME_ALLOW_LOCAL_INSTANCE=1 \+ node --env-file=.env.local node_modules/.bin/vitest run tests/home-turn-gate.test.js+```++`HOME_ALLOW_LOCAL_INSTANCE` has to be exported before the run rather than set inside it:+[`api/_lib/home-url-guard.js`](../api/_lib/home-url-guard.js) reads it into a module-level constant+the first time it is imported, so a value set later arrives too late and every call is refused as a+private address. The block fails with that explanation rather than the confusing symptom.++**Commitment 2, the downgrade, and commitment 3, the quota display.** The two journeys in+[`tests/e2e/home-plan.spec.js`](../tests/e2e/home-plan.spec.js) open `/smart-home/plan` in a real+browser against a real API and a real house. The first asserts every dimension renders with its+usage and a real reset date before anything is near a ceiling. The second clicks Pause on a+connected home and proves on screen that the row stays, is labelled paused, keeps its credential,+and can be made live again.++```bash+HOME_E2E_API_PORT=8171 HOME_E2E_WEB_PORT=3031 HOME_LIVE=1 HOME_LIVE_NAME=plan19 \+ npx playwright test --config playwright.home.config.js tests/e2e/home-plan.spec.js+```++The journeys pause by clicking the button, never by posting to `/api/home/plan` directly: that+route is CSRF-guarded like every other state change, so a raw request would have to mint a token+the product mints for itself, and the test would then be exercising a path no user takes.diff --git a/playwright.home.config.js b/playwright.home.config.jsindex 280d9d947..62ec8a058 100644--- a/playwright.home.config.js+++ b/playwright.home.config.js@@ -1,5 +1,8 @@import { defineConfig } from '@playwright/test';import { randomBytes } from 'node:crypto';+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';/*** The home lane's own Playwright config.@@ -16,6 +19,31 @@ import { randomBytes } from 'node:crypto';* the process, so nothing here can decrypt a production credential and nothing* production wrote can be read by this run.*/+// The database, in THIS process and not only in the API child process.+//+// The API server below is started with `node --env-file=.env.local`, so it has+// always had DATABASE_URL. The Playwright process did not: the global setup+// provisions QA accounts and the specs read and write home rows directly, and+// both of those run here. Without this the whole run dies before the first+// browser opens with "Missing required env var: DATABASE_URL" thrown from+// api/_lib/env.js, which reads as a product bug and is a missing variable.+//+// Same precedence as scripts/apply-migrations.mjs: a value already in the+// environment wins, then .env.local, then .env. So `DATABASE_URL=... npx+// playwright test` still points the run wherever the caller aimed it.+const CONFIG_DIR = path.dirname(fileURLToPath(import.meta.url));+for (const envFile of ['.env.local', '.env']) {+ try {+ for (const line of readFileSync(path.resolve(CONFIG_DIR, envFile), 'utf8').split('\n')) {+ const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);+ if (!m || process.env[m[1]]) continue;+ const val = m[2].trim();+ const quoted = (val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"));+ process.env[m[1]] = quoted ? val.slice(1, -1) : val;+ }+ } catch { /* not present: an exported DATABASE_URL is a valid way to run this */ }+}+// Dedicated ports, and no server reuse. Other agents run their own `npm run// dev` on :3000 in this worktree, and reusing one is not a smaller version of// this stack: its /api proxy points at PRODUCTION, so the run silently tests@@ -83,7 +111,31 @@ export default defineConfig({reuseExistingServer: false,stdout: 'pipe',stderr: 'pipe',- env: { DEV_API_PROXY: `http://127.0.0.1:${API_PORT}` },+ env: {+ DEV_API_PROXY: `http://127.0.0.1:${API_PORT}`,+ // No hot reload, for two independent reasons.+ //+ // The noisy one: vite.config.js points the HMR client at+ // `<codespace>-<port>.app.github.dev` whenever it sees+ // CODESPACE_NAME, which is right for a developer opening a+ // forwarded port and wrong here, where the browser is headless,+ // reaches vite on localhost, and the lane's port is not+ // forwarded. The handshake 404s and every page collects three+ // console errors and a pageerror it did not cause, which a+ // journey asserting a clean console then fails on.+ //+ // The damaging one, and the reason this is off rather than+ // merely repointed: concurrent agents edit src/ in this shared+ // worktree while a journey is running, and a connected HMR+ // client reloads the page on each of their saves. Journey 9e+ // died exactly that way, on a navigation that arrived between+ // naming a room and clicking File.+ //+ // Deliberately not solved by widening a spec's console-noise+ // filter: that would hide the errors and keep the reloads, and+ // the home lane has real websockets of its own to assert on.+ VITE_NO_HMR: '1',+ },},],});diff --git a/tests/api-home.test.js b/tests/api-home.test.jsindex 7009056d1..a4b51ccd7 100644--- a/tests/api-home.test.js+++ b/tests/api-home.test.js@@ -12,8 +12,8 @@// that need a live socket (the guarded 409, the SSE stream) are gated on a real// Home Assistant through tests/_helpers/home-instance.js and skip without one.-import { afterAll, beforeAll, describe, expect, it } from 'vitest';-import { randomUUID } from 'node:crypto';+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';+import { randomBytes, randomUUID } from 'node:crypto';import '../tests/setup.env.js';import { acquireHomeInstance, liveHomeAvailable, pickEntity } from './_helpers/home-instance.js';@@ -381,8 +381,18 @@ d('every refusal leaves a row an owner can read', () => {live('against a real house', () => {let instance;let liveHomeId;+ let stubbedKey = false;beforeAll(async () => {+ // Unlike the `dk` suites above, this block cannot be gated on HAS_KEY and+ // still do its job: skipping it on a machine with a real house attached+ // would silently drop the only live coverage this file has. It writes a+ // connection, so it needs a key, and a per-run one thrown away with the+ // process encrypts nothing but the rows created and deleted here.+ if (!process.env.WALLET_ENCRYPTION_KEY && !process.env.JWT_SECRET) {+ vi.stubEnv('WALLET_ENCRYPTION_KEY', randomBytes(32).toString('hex'));+ stubbedKey = true;+ }instance = await acquireHomeInstance();const created = await store.createConnection({userId: users.owner,@@ -394,6 +404,10 @@ live('against a real house', () => {liveHomeId = created.id;}, 600_000);+ afterAll(() => {+ if (stubbedKey) vi.unstubAllEnvs();+ });+it('serves a snapshot with the house’s real rooms', async () => {const res = mkRes();await handlers.byId(mkReq({ who: 'owner', id: liveHomeId }), res);diff --git a/tests/e2e/home-plan.spec.js b/tests/e2e/home-plan.spec.jsindex 93e1b2cdd..2f99a15a6 100644--- a/tests/e2e/home-plan.spec.js+++ b/tests/e2e/home-plan.spec.js@@ -58,38 +58,48 @@ test.describe('the plan page', () => {});test('a paused home is shown as paused, keeps its row, and can be swapped back', async ({ page }) => {- await connectHome(page, { label: 'Paused house journey' });+ const label = await connectHome(page, { label: 'Paused house journey' });const before = await (await page.request.get('/api/home', { timeout: 60_000 })).json();const homes = Array.isArray(before?.homes) ? before.homes : before;expect(homes.length).toBeGreaterThan(0);- const target = homes[homes.length - 1];+ const target = homes.find((h) => h.label === label) || homes[homes.length - 1];await page.goto('/smart-home/plan', { waitUntil: 'domcontentloaded' });- // Pause through the page's own endpoint, which is what a plan change does.- const paused = await page.request.post('/api/home/plan', {- data: { action: 'pause', home_id: target.id },- headers: { 'content-type': 'application/json' },- timeout: 60_000,- });- expect(paused.ok()).toBe(true);+ // Pause by CLICKING, not by posting.+ //+ // An earlier version of this journey called POST /api/home/plan directly and+ // failed on a 403, because that route is CSRF-guarded like every other state+ // change and a raw page.request.post carries the session cookie without the+ // header. Minting a token in the spec would have made the journey pass while+ // testing a path no user takes. The button is the path a user takes, and it+ // exercises the token mint in src/home/api.js on the way through.+ const card = page.locator('.hm-card').filter({ hasText: label }).first();+ await expect(card).toBeVisible({ timeout: 30_000 });+ await card.getByRole('button', { name: 'Pause', exact: true }).click();++ // Commitment 2 on screen: the row is still there, and it says paused rather+ // than having quietly vanished the way a disconnect would.+ const pausedCard = page.locator('.hm-card').filter({ hasText: label }).first();+ await expect(pausedCard.getByText('Paused', { exact: true })).toBeVisible({ timeout: 30_000 });+ await expect(pausedCard.getByRole('button', { name: 'Make live' })).toBeVisible();- await page.reload({ waitUntil: 'domcontentloaded' });- await expect(page.getByText(/paused/i).first()).toBeVisible({ timeout: 30_000 });+ await page.screenshot({ path: 'test-results/home-plan-paused.png', fullPage: true });- // The row is intact: it still lists, it is not revoked, and it can come back.+ // Nothing was deleted and nothing was revoked: the row is intact in the API+ // the moment the page says it is paused.const after = await (await page.request.get('/api/home', { timeout: 60_000 })).json();const stillThere = (Array.isArray(after?.homes) ? after.homes : after).find((h) => h.id === target.id);expect(stillThere).toBeTruthy();-- await page.screenshot({ path: 'test-results/home-plan-paused.png', fullPage: true });-- const resumed = await page.request.post('/api/home/plan', {- data: { action: 'resume', home_id: target.id },- headers: { 'content-type': 'application/json' },- timeout: 60_000,- });- expect(resumed.ok()).toBe(true);+ expect(stillThere.revoked_at ?? null).toBeNull();++ // And the choice is reversible, which is the half of commitment 2 that makes+ // the pause acceptable in the first place.+ await pausedCard.getByRole('button', { name: 'Make live' }).click();+ await expect(+ page.locator('.hm-card').filter({ hasText: label }).first()+ .getByRole('button', { name: 'Pause', exact: true }),+ ).toBeVisible({ timeout: 30_000 });});});diff --git a/tests/home-tools.test.js b/tests/home-tools.test.jsindex 959d6baee..520560d02 100644--- a/tests/home-tools.test.js+++ b/tests/home-tools.test.js@@ -24,10 +24,11 @@// Every live assertion reads the lock's state back from Home Assistant. A tool// result that says "pending" proves nothing about a door.-import { afterAll, beforeAll, describe, expect, it } from 'vitest';+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';import { buildHomeGraph } from '@three-ws/home-bridge';+import { randomBytes } from 'node:crypto';import { readFileSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';@@ -133,8 +134,19 @@ live('against a real Home Assistant', () => {let lightId;const asOwner = (tool, args) => runHomeTool(tool, args, { userId: owner.id, source: 'mcp' });+ let stubbedKey = false;beforeAll(async () => {+ // The connection row's token is encrypted at rest, so createConnection+ // below needs a key. A machine with neither of these set failed the whole+ // live block with "Missing required env var: JWT_SECRET" raised from+ // secret-box, which reads as a broken handler and is a missing variable.+ // Generated per run and thrown away with the process: it encrypts only the+ // rows this block creates and deletes.+ if (!process.env.WALLET_ENCRYPTION_KEY && !process.env.JWT_SECRET) {+ vi.stubEnv('WALLET_ENCRYPTION_KEY', randomBytes(32).toString('hex'));+ stubbedKey = true;+ }instance = await acquireHomeInstance();({ sql } = await import('../api/_lib/db.js'));const { createConnection } = await import('../api/_lib/home/store.js');@@ -159,6 +171,7 @@ live('against a real Home Assistant', () => {const { closeAll } = await import('../api/_lib/home/runtime.js');closeAll();if (sql && owner) await sql`delete from users where id in (${owner.id}, ${stranger.id})`;+ if (stubbedKey) vi.unstubAllEnvs();});it('reads the real house', async () => {diff --git a/tests/home-turn-gate.test.js b/tests/home-turn-gate.test.jsindex 5b086ad02..94b9a9514 100644--- a/tests/home-turn-gate.test.js+++ b/tests/home-turn-gate.test.js@@ -6,9 +6,11 @@// agent to lock up, close a garage or a valve, or arm an alarm still runs, and// asking it what the house is doing still answers.-import { describe, expect, it, vi } from 'vitest';+import { randomBytes } from 'node:crypto';-import { HomeQuotaError, UNLIMITED } from '../api/_lib/home/entitlements.js';+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';++import { assertHomeActionAllowed, HomeQuotaError, UNLIMITED } from '../api/_lib/home/entitlements.js';import {homeCallShape,homeTurnGate,@@ -16,6 +18,14 @@ import {quotaRefusalResult,shouldRefuseHomeCall,} from '../api/_lib/home/turn-gate.js';+import {+ acquireHomeInstance,+ liveHomeAvailable,+ pickEntity,+ readState,+ setState,+ waitForState,+} from './_helpers/home-instance.js';const OVER = { allowed: false, error: new HomeQuotaError({ dimension: 'agentTurns', limit: 1000, used: 1000, resetAt: '2026-10-01T00:00:00.000Z' }) };const UNDER = { allowed: true, error: null };@@ -184,3 +194,202 @@ describe('the refusal the model speaks', () => {expect(r.structured.resets_at).toBe('2026-10-01T00:00:00.000Z');});});++// ── The same commitment, against a real house ────────────────────────────────+//+// Everything above classifies a call. Classifying it right is not the same as+// the deadbolt moving, and the line this order exists to keep is about the+// deadbolt. So this block puts a real account past a real ceiling, pauses its+// real home the way a downgrade does, and then asks a real Home Assistant to+// lock up. The assertion is the state read back out of the house.+//+// The account is put over quota through the override row rather than by+// burning a thousand turns: the override is the same code path a limit of any+// size takes, and a test that had to spend an hour of model calls to reach a+// ceiling is a test nobody runs.++// HOME_ALLOW_LOCAL_INSTANCE has to be exported BEFORE the run, not set from+// inside it: api/_lib/home-url-guard.js reads it into a module-level const when+// it is first imported, which happens above this line. Without it every call+// below is refused with "127.0.0.1 is a private address", which reads as a+// product bug and is a missing variable. The whole command is:+//+// HOME_LIVE=1 HOME_LIVE_NAME=<lane> HOME_ALLOW_LOCAL_INSTANCE=1 \+// node --env-file=.env.local node_modules/.bin/vitest run tests/home-turn-gate.test.js+const live = describe.skipIf(!liveHomeAvailable() || !process.env.DATABASE_URL);++live('over quota and paused, against a real Home Assistant', () => {+ /** @type {any} */ let sql;+ let instance;+ let owner;+ let home;+ let gate;+ let stubbedKey = false;+ const entity = {};++ const call = (domain, service, entityId, extra = {}) => ({+ name: 'home_call',+ input: { domain, service, data: { entity_id: entityId, ...extra } },+ });++ // A real alarm panel takes a code, and this house's does: the demo panel+ // reports code_arm_required and refuses an arm without one. It rides in the+ // call's data, which is where a user's panel code would ride too, and it+ // changes nothing about the classification: the exemption is decided from the+ // domain and the service alone.+ const ALARM_CODE = '1234';++ beforeAll(async () => {+ // The connection row's access token is encrypted at rest, so creating one+ // needs a key. Generated per run and thrown away with the process: it+ // encrypts only the rows this block creates and deletes, exactly as in+ // tests/home-security.test.js.+ if (!process.env.WALLET_ENCRYPTION_KEY && !process.env.JWT_SECRET) {+ vi.stubEnv('WALLET_ENCRYPTION_KEY', randomBytes(32).toString('hex'));+ stubbedKey = true;+ }+ instance = await acquireHomeInstance();+ if (process.env.HOME_ALLOW_LOCAL_INSTANCE !== '1') {+ throw new Error(+ 'Set HOME_ALLOW_LOCAL_INSTANCE=1 in the environment before this run: the URL guard '+ + 'caches it at import time, so setting it here is too late and every call would be '+ + 'refused as a private address.',+ );+ }+ ({ sql } = await import('../api/_lib/db.js'));+ const { createConnection } = await import('../api/_lib/home/store.js');+ const { setAccountOverride } = await import('../api/_lib/home/entitlements.js');++ [owner] = await sql`+ insert into users (email) values (${`home-gate-${Date.now()}@qa.three.ws`}) returning id+ `;+ home = await createConnection({+ userId: owner.id,+ label: 'Over quota house',+ baseUrl: instance.baseUrl,+ token: instance.token,+ status: 'connected',+ });++ // Every dimension at zero: there is no allowance left anywhere on this+ // account, which is the harshest state the product can put a user in.+ await setAccountOverride({+ userId: owner.id,+ limits: { homes: 0, members: 0, streams: 0, voiceMinutes: 0, agentTurns: 0, relayConnections: 0 },+ note: 'tests/home-turn-gate.test.js: the safety exemption, proved against a real house',+ });+ // And the home paused, as a downgrade would leave it.+ await sql`+ update home_connections+ set deactivated_at = now(), deactivated_reason = 'Paused by this test'+ where id = ${home.id}+ `;+ [home] = await sql`select * from home_connections where id = ${home.id}`;++ gate = await homeTurnGate(owner.id);++ // A lock that is NOT the first one in the house.+ //+ // vitest runs test FILES in parallel and every live block in this lane+ // drives the SAME physical house, so two files both taking the first lock+ // end up asserting on each other's transitions: tests/home-tools.test.js+ // read 'locking' where it expected 'locked' the moment this block landed.+ // Taking a different deadbolt costs nothing and removes the whole class.+ const firstLock = await pickEntity(instance, 'lock');+ entity.lock = await pickEntity(instance, 'lock', (state) => state.entity_id !== firstLock);+ entity.cover = await pickEntity(instance, 'cover');+ entity.alarm = await pickEntity(instance, 'alarm_control_panel');+ entity.light = await pickEntity(instance, 'light');++ // Start each device in the state a safety action moves it OUT of, so a+ // pass cannot come from a device that was already where we want it.+ await setState(instance, 'lock', 'unlock', entity.lock);+ await setState(instance, 'cover', 'open_cover', entity.cover);+ await disarmAlarm();+ await waitForState(instance, entity.lock, 'unlocked');+ }, 600_000);++ afterAll(async () => {+ const { closeAll } = await import('../api/_lib/home/runtime.js');+ closeAll();+ if (instance && entity.lock) await setState(instance, 'lock', 'lock', entity.lock).catch(() => {});+ if (instance && entity.alarm) await disarmAlarm().catch(() => {});+ if (sql && owner) {+ await sql`delete from home_plan_overrides where user_id = ${owner.id}`.catch(() => {});+ await sql`delete from home_connections where user_id = ${owner.id}`.catch(() => {});+ await sql`delete from users where id = ${owner.id}`.catch(() => {});+ }+ if (stubbedKey) vi.unstubAllEnvs();+ });++ /** The demo panel refuses a bare disarm, so the code goes in the body. */+ async function disarmAlarm() {+ const res = await fetch(`${instance.baseUrl}/api/services/alarm_control_panel/alarm_disarm`, {+ method: 'POST',+ headers: { authorization: `Bearer ${instance.token}`, 'content-type': 'application/json' },+ body: JSON.stringify({ entity_id: entity.alarm, code: ALARM_CODE }),+ signal: AbortSignal.timeout(15_000),+ });+ if (!res.ok) throw new Error(`alarm_disarm returned ${res.status}`);+ }++ it('the account really is over its agent-turn quota', () => {+ expect(gate.allowed).toBe(false);+ expect(gate.error).toBeInstanceOf(HomeQuotaError);+ expect(gate.error.dimension).toBe('agentTurns');+ });++ // The three transcripts this order is written around. Each one asserts the+ // device, read back from Home Assistant, and not the return value of our own+ // classifier.+ const transcripts = [+ { key: 'lock', domain: 'lock', service: 'lock', from: 'unlocked', to: ['locked', 'locking'] },+ { key: 'cover', domain: 'cover', service: 'close_cover', from: 'open', to: ['closed', 'closing'] },+ {+ key: 'alarm',+ domain: 'alarm_control_panel',+ service: 'alarm_arm_away',+ from: 'disarmed',+ to: ['armed_away', 'arming'],+ data: { code: ALARM_CODE },+ },+ ];++ for (const t of transcripts) {+ it(`${t.domain}.${t.service} still runs, and the device moves`, async () => {+ const { runHomeTool } = await import('../api/_lib/home/tools.js');+ const entityId = entity[t.key];+ expect(await readState(instance, entityId)).toBe(t.from);++ // Both gates, in the order a real request meets them: the chat lane's+ // quota check, then the REST lane's paused-home check.+ expect(shouldRefuseHomeCall(gate, call(t.domain, t.service, entityId, t.data))).toBe(false);+ expect(() => assertHomeActionAllowed({ home, call: { domain: t.domain, service: t.service } }))+ .not.toThrow();++ const result = await runHomeTool(+ 'home_call',+ { home_id: home.id, domain: t.domain, service: t.service, data: { entity_id: entityId, ...t.data } },+ { userId: owner.id, source: 'mcp' },+ );+ expect(result.ok, `${t.domain}.${t.service} was refused: ${result.text}`).toBe(true);++ await new Promise((resolve) => setTimeout(resolve, 1500));+ expect(t.to).toContain(await readState(instance, entityId));+ }, 120_000);+ }++ it('an ordinary action on the same account, in the same moment, IS refused', async () => {+ // Without this the block above would also pass on a gate that had simply+ // stopped working. The exemption has to be selective to mean anything.+ expect(shouldRefuseHomeCall(gate, call('light', 'turn_on', entity.light))).toBe(true);+ expect(() => assertHomeActionAllowed({ home, call: { domain: 'light', service: 'turn_on' } }))+ .toThrow();+ });++ it('and the unsafe direction of a safety domain is still refused', () => {+ expect(shouldRefuseHomeCall(gate, call('lock', 'unlock', entity.lock))).toBe(true);+ expect(() => assertHomeActionAllowed({ home, call: { domain: 'lock', service: 'unlock' } }))+ .toThrow();+ });+});