Skip to content

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.

feat(home): ship the relay service, the MCP surface and the privacy window

nirholase71b1fe1f3d5
diff --git a/.gitignore b/.gitignore
index 654bbabc0..561d1e7fd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -538,6 +538,9 @@ download.zip
# Same thing at fleet scale: scripts/home-fleet.mjs boots numbered Home Assistant
# instances under .home-fleet/<n>/, each with its own token store.
.home-fleet/
+# The fleet registry that pairs those instances with their long-lived access
+# tokens. Local state about local containers; the tokens make it uncommittable.
+tasks/home/*.local.json
# Browser voice-loop runtime staged from node_modules by scripts/copy-voice-models.mjs
# (silero VAD + the onnxruntime-web wasm). Regenerated on every install and
diff --git a/api/_lib/home/privacy.js b/api/_lib/home/privacy.js
new file mode 100644
index 000000000..ae78bff4d
--- /dev/null
+++ b/api/_lib/home/privacy.js
@@ -0,0 +1,538 @@
+// The Home lane's data inventory, and the code that acts on it.
+//
+// Everything three.ws stores about a person's house is enumerated once, here,
+// in INVENTORY. That list is not documentation of the code: it IS the code.
+// The privacy endpoint renders it, the export walks it, the deletion walks it,
+// and tests/home-privacy.test.js re-derives the set of home_* tables from the
+// migration files and fails if one of them is missing from it. A data class
+// nobody wrote down is the failure this structure exists to prevent, so adding
+// a table to this campaign without adding a row here breaks the build.
+//
+// The promise this module keeps, and the reason it can keep it
+// ----------------------------------------------------------
+// **Entity states are never persisted.** Not the room graph, not the entity
+// list, not a history of which light was on when. Those live in the bridge
+// runtime's memory and die with the instance. A stored record of "the bedroom
+// light went on at 23:14" is an occupancy log for a building, and this campaign
+// does not create one: read the schema and there is nowhere for it to go. The
+// completeness test asserts that too, by checking every persisted home table
+// against this list.
+//
+// Voice audio is stored nowhere, ever. A transcript lives in the conversation
+// turn that produced it and is gone with it.
+//
+// Deletion vs revoke
+// ------------------
+// `revokeConnection` in store.js is a DISCONNECT: it scrubs the credential and
+// keeps the row, so an owner can still answer "what did my agent do in my house
+// last Tuesday" about a house they have since unplugged. That is the right
+// default and it is not deletion. `deleteHome` here is the other verb: the row
+// and everything that points at it go, and nothing is left to read.
+
+import { sql } from '../db.js';
+import { withDbRetry } from '../db-retry.js';
+
+/** The 90-day default, stated once so the doc, the UI and the DB agree. */
+export const DEFAULT_ACTION_LOG_RETENTION_DAYS = 90;
+/** The bounds the schema check constraint enforces. Mirrored, never guessed. */
+export const MIN_ACTION_LOG_RETENTION_DAYS = 1;
+export const MAX_ACTION_LOG_RETENTION_DAYS = 3650;
+/** Past this, an extension has to say why, in at least this many characters. */
+export const RETENTION_REASON_MIN_LENGTH = 8;
+
+/**
+ * Every durable thing this lane holds, in the words a person would use.
+ *
+ * `table: null` marks a data class we deliberately do NOT persist. Those rows
+ * are the most important entries in the list: they are the promises, and the
+ * completeness test proves the schema has nowhere to break them.
+ *
+ * @type {ReadonlyArray<{
+ * key: string, data: string, table: string|null, why: string,
+ * retention: string, deletedBy: string, sensitive?: boolean
+ * }>}
+ */
+export const INVENTORY = Object.freeze([
+ {
+ key: 'connection',
+ data: 'The address of your home and the label you gave it',
+ table: 'home_connections',
+ why: 'To reach your Home Assistant at all.',
+ retention: 'Until you disconnect the home; the row is deleted when you delete the home.',
+ deletedBy: 'Delete this home, or delete your account.',
+ },
+ {
+ key: 'credential',
+ data: 'Your Home Assistant access token, encrypted',
+ table: 'home_connections',
+ why: 'Home Assistant requires it on every connection, so we have to be able to replay it.',
+ retention: 'Encrypted at rest (AES-256-GCM) and erased the moment you disconnect the home, before the row itself is deleted.',
+ deletedBy: 'Disconnect, delete this home, or delete your account.',
+ sensitive: true,
+ },
+ {
+ key: 'capabilities',
+ data: 'What your instance turned out to be: its version, how many entities and areas it has, whether it exposes MCP',
+ table: 'home_connections',
+ why: 'So the connect screen and the agent can tell you what is actually available instead of guessing.',
+ retention: 'Until the home is deleted. Counts only, never the entity or area names themselves.',
+ deletedBy: 'Delete this home, or delete your account.',
+ },
+ {
+ key: 'entity_names',
+ data: 'The names of your rooms, devices and scenes',
+ table: null,
+ why: 'To draw your home and to understand what you ask for.',
+ retention: 'Never stored. They are read live from your Home Assistant and held in memory only for as long as the connection is open.',
+ deletedBy: 'Nothing to delete.',
+ },
+ {
+ key: 'entity_states',
+ data: 'Whether a light is on, a door is locked, a room is warm',
+ table: null,
+ why: 'To render your home live and to answer questions about it.',
+ retention: 'Never stored. A record of when your lights go on and off is a record of when you are home, and we do not keep one.',
+ deletedBy: 'Nothing to delete.',
+ },
+ {
+ key: 'members',
+ data: 'Who else you gave access to this home, and what role they have',
+ table: 'home_members',
+ why: 'So a household or a building can share one home without sharing one login.',
+ retention: 'Until the member is removed or the home is deleted.',
+ deletedBy: 'Remove the member, delete this home, or delete your account.',
+ },
+ {
+ key: 'invites',
+ data: 'The email address of someone you invited, until they accept or it expires',
+ table: 'home_invites',
+ why: 'To send and to honour an invitation to your home.',
+ retention: 'Until accepted, revoked, or expired; deleted with the home. Deleting your account also removes invitations addressed to your email.',
+ deletedBy: 'Revoke the invite, delete this home, or delete your account.',
+ sensitive: true,
+ },
+ {
+ key: 'grants',
+ data: 'The standing permissions you granted: which specific door or alarm the agent may open without asking again',
+ table: 'home_entity_grants',
+ why: 'You granted them, so that the agent stops asking about the one thing you said yes to.',
+ retention: 'Until you revoke the grant, until it expires, or until the home is deleted. A grant is also removed when the person who granted it deletes their account.',
+ deletedBy: 'Revoke the grant, delete this home, or delete your account.',
+ },
+ {
+ key: 'action_log',
+ data: 'Every action the agent took in your home: what it did, to which entities, whether it had to ask you first, and whether it worked',
+ table: 'home_action_log',
+ why: 'So you can answer "what did my agent do in my house" without taking our word for it.',
+ retention: 'Your choice, 90 days by default. You can shorten it to a single day, or lengthen it if you run a building that has to keep records.',
+ deletedBy: 'The daily retention sweep, deleting this home, or deleting your account.',
+ sensitive: true,
+ },
+ {
+ key: 'voice_audio',
+ data: 'The sound of your voice',
+ table: null,
+ why: 'Speech has to be turned into words.',
+ retention: 'Never stored. Audio is processed and discarded within the turn that produced it.',
+ deletedBy: 'Nothing to delete.',
+ },
+ {
+ key: 'voice_transcript',
+ data: 'What you said, as text',
+ table: null,
+ why: 'The agent has to know what you asked for.',
+ retention: 'Never stored by this lane. It lives in the conversation you are having and goes when that conversation does.',
+ deletedBy: 'Clear the conversation.',
+ },
+]);
+
+/** The tables the inventory says exist. The completeness test reads this. */
+export const INVENTORY_TABLES = Object.freeze(
+ [...new Set(INVENTORY.map((row) => row.table).filter(Boolean))].sort(),
+);
+
+/**
+ * Tables that hold a user's home data but are NOT reachable from a home_id.
+ * Deletion has to sweep them by user, not by cascade, or an identifier survives
+ * the account it belonged to.
+ */
+export const USER_SCOPED_RESIDUE = Object.freeze([
+ // The action log's actor columns carry no foreign key on purpose: an actor can
+ // be an agent principal with no account behind it. That also means nothing
+ // removes a departed user's id from another household's log, so deletion
+ // scrubs those columns by hand rather than trusting a cascade that is not
+ // there.
+ 'home_action_log.user_id',
+ 'home_action_log.confirmed_by',
+ // An invitation addressed to an email is addressed to a person, and it lives
+ // on somebody else's home, so no cascade from the user reaches it.
+ 'home_invites.email',
+ // The platform audit trail records home disconnects. Its rows outlive the
+ // account (user_id is set null, not deleted), so home-scoped rows are removed
+ // explicitly here.
+ 'audit_log',
+]);
+
+// ── Retention ────────────────────────────────────────────────────────────────
+
+/**
+ * Set how long this home keeps its action log.
+ *
+ * Shortening never needs a justification: keeping less of somebody's data is not
+ * the decision that has to be defended. Lengthening past the 90-day default
+ * does, because a building that keeps two years of occupancy data will be asked
+ * why, and the answer should be on the record before the question arrives. The
+ * schema enforces the same rule, so a caller that skips this function cannot
+ * skip the rule.
+ *
+ * @param {object} input
+ * @param {string} input.homeId
+ * @param {string} input.userId the owner; the update is ownership-filtered in SQL
+ * @param {number} input.days
+ * @param {string|null} [input.reason] required above the default window
+ * @returns {Promise<{ ok: boolean, code?: string, home?: object }>}
+ */
+export async function setActionLogRetention({ homeId, userId, days, reason = null }) {
+ const n = Number.parseInt(String(days), 10);
+ if (!Number.isFinite(n) || n < MIN_ACTION_LOG_RETENTION_DAYS || n > MAX_ACTION_LOG_RETENTION_DAYS) {
+ return { ok: false, code: 'bad_retention_days' };
+ }
+ const trimmed = typeof reason === 'string' ? reason.trim() : '';
+ if (n > DEFAULT_ACTION_LOG_RETENTION_DAYS && trimmed.length < RETENTION_REASON_MIN_LENGTH) {
+ return { ok: false, code: 'reason_required' };
+ }
+ const storedReason = n > DEFAULT_ACTION_LOG_RETENTION_DAYS ? trimmed.slice(0, 500) : null;
+
+ const rows = await sql`
+ update home_connections
+ set action_log_retention_days = ${n},
+ action_log_retention_reason = ${storedReason},
+ action_log_retention_set_by = ${userId},
+ action_log_retention_set_at = now(),
+ updated_at = now()
+ where id = ${homeId} and user_id = ${userId}
+ returning id, action_log_retention_days, action_log_retention_reason, action_log_retention_set_at
+ `;
+ if (!rows[0]) return { ok: false, code: 'not_found' };
+
+ // Applying the new window immediately is the point. A user who shortens
+ // retention to a day expects yesterday's rows to be gone now, not at the next
+ // sweep, and telling them "within 24 hours" when we could simply do it is a
+ // worse product and a worse promise.
+ const purged = await purgeActionLogForHome(homeId, n);
+ return { ok: true, home: rows[0], purged };
+}
+
+/**
+ * Delete this home's action-log rows past a given window.
+ *
+ * Bounded and idempotent: it deletes only rows older than the window and nothing
+ * else, so running it twice is the same as running it once, and running it on a
+ * home with a long window is a no-op.
+ *
+ * @param {string} homeId
+ * @param {number} days
+ * @returns {Promise<number>} rows deleted
+ */
+export async function purgeActionLogForHome(homeId, days) {
+ const n = Number.parseInt(String(days), 10);
+ if (!Number.isFinite(n) || n < MIN_ACTION_LOG_RETENTION_DAYS) return 0;
+ const del = await sql`
+ delete from home_action_log
+ where home_id = ${homeId}
+ and created_at < now() - ${n} * interval '1 day'
+ returning id
+ `;
+ return del.length;
+}
+
+/**
+ * The sweep, for the retention cron.
+ *
+ * Every home carries its own window, so this cannot be one DELETE with one
+ * cutoff. It joins the log against its home's setting instead, which keeps the
+ * whole policy in the database rather than half of it in a cron's environment.
+ *
+ * Bounded per call so a single tick can never run away: the caller re-runs on
+ * its schedule and a backlog drains over a few ticks.
+ *
+ * @param {{ batch?: number, maxRows?: number }} [options]
+ * @returns {Promise<{ deleted: number, batches: number, homes: number }>}
+ */
+export async function purgeExpiredActionLog({ batch = 5000, maxRows = 100_000 } = {}) {
+ let deleted = 0;
+ let batches = 0;
+ const homes = new Set();
+ const maxBatches = Math.max(1, Math.ceil(maxRows / batch));
+
+ for (let i = 0; i < maxBatches; i++) {
+ // The cutoff is per row, read from the row's own home. `ctid` keeps the
+ // statement bounded without needing a stable ordering over a bigserial that
+ // another writer is appending to concurrently.
+ const del = await sql`
+ delete from home_action_log
+ where ctid in (
+ select l.ctid
+ from home_action_log l
+ join home_connections h on h.id = l.home_id
+ where l.created_at < now() - h.action_log_retention_days * interval '1 day'
+ limit ${batch}
+ )
+ returning home_id
+ `;
+ batches += 1;
+ deleted += del.length;
+ for (const row of del) homes.add(row.home_id);
+ if (del.length < batch) break;
+ }
+ return { deleted, batches, homes: homes.size };
+}
+
+// ── Export ───────────────────────────────────────────────────────────────────
+
+/**
+ * Everything this lane holds about one person, as plain JSON.
+ *
+ * Walks the inventory rather than a hand-written list of queries, so a table
+ * that gets added to the campaign and to INVENTORY is exported without anybody
+ * remembering to come back here. The credential is the single deliberate
+ * omission: exporting a decrypted key to someone's front door into a file that
+ * lands in a downloads folder would be a worse privacy outcome than not
+ * exporting it, so the export carries the fact that a credential exists and its
+ * fingerprint, never the key.
+ *
+ * @param {string} userId
+ * @returns {Promise<object>}
+ */
+export async function exportHomeData(userId) {
+ const homes = await sql`
+ select id, label, base_url, token_fingerprint, transport, relay_id, capabilities,
+ status, status_detail, last_ok_at, last_error_at, created_at, updated_at,
+ revoked_at, action_log_retention_days, action_log_retention_reason,
+ action_log_retention_set_at
+ from home_connections
+ where user_id = ${userId}
+ order by created_at
+ `;
+ const homeIds = homes.map((h) => h.id);
+
+ const [members, invites, grants, actions, invitesToMe] = await Promise.all([
+ homeIds.length
+ ? sql`select home_id, user_id, role, entity_scope, invited_by, created_at, updated_at
+ from home_members where home_id = any(${homeIds}) order by home_id, created_at`
+ : [],
+ homeIds.length
+ ? sql`select id, home_id, email, role, entity_scope, invited_by, expires_at,
+ accepted_at, accepted_by, revoked_at, created_at
+ from home_invites where home_id = any(${homeIds}) order by home_id, created_at`
+ : [],
+ homeIds.length
+ ? sql`select home_id, entity_id, granted_by, expires_at, created_at
+ from home_entity_grants where home_id = any(${homeIds}) order by home_id, entity_id`
+ : [],
+ homeIds.length
+ ? sql`select id, home_id, user_id, actor, channel, action, entity_ids, guarded,
+ confirmed_by, risk, outcome, detail, created_at
+ from home_action_log where home_id = any(${homeIds}) order by home_id, created_at`
+ : [],
+ // Homes somebody else owns that you are a member of, and invitations
+ // addressed to you: both are data about you that a query scoped to homes
+ // you own would miss entirely.
+ sql`select m.home_id, m.role, m.entity_scope, m.created_at
+ from home_members m where m.user_id = ${userId} order by m.created_at`,
+ ]);
+
+ return {
+ generated_at: new Date().toISOString(),
+ notice:
+ 'This is everything three.ws stores about your connected homes. Your Home Assistant access token is deliberately not included: it is a key to your building and it does not belong in a downloads folder. Room names, device names and device states are absent because we never store them.',
+ inventory: INVENTORY,
+ homes_you_own: homes,
+ memberships: invitesToMe,
+ members,
+ invites,
+ grants,
+ action_log: actions,
+ };
+}
+
+// ── Deletion ─────────────────────────────────────────────────────────────────
+
+/**
+ * Delete one home and everything that points at it.
+ *
+ * The foreign keys cascade, and this function does not take that on trust: it
+ * counts the dependent rows before and after and returns both, so a caller (and
+ * a test) can assert the cascade actually fired rather than assuming a schema
+ * comment is still true.
+ *
+ * Ownership is a SQL filter, never a JavaScript check after the fact: a home
+ * that is not yours returns `{ deleted: false }` and is indistinguishable from
+ * one that does not exist.
+ *
+ * @param {string} homeId
+ * @param {string} userId
+ * @returns {Promise<{ deleted: boolean, before: object, after: object }>}
+ */
+export async function deleteHome(homeId, userId) {
+ const owned = await sql`select id from home_connections where id = ${homeId} and user_id = ${userId}`;
+ if (!owned[0]) return { deleted: false, before: {}, after: {} };
+
+ const before = await countHomeRows(homeId);
+
+ // audit_log has no home_id column and no cascade: its rows reference the home
+ // by resource_id and survive both the home and the account. Remove ours by
+ // hand, or "delete my home" leaves the home's address in a table with a
+ // 365-day window.
+ await sql`delete from audit_log where resource_id = ${homeId} and action like 'home\\_%'`;
+
+ await sql`delete from home_connections where id = ${homeId} and user_id = ${userId}`;
+
+ const after = await countHomeRows(homeId);
+ return { deleted: true, before, after };
+}
+
+/**
+ * Every home row this user has, gone, plus the identifiers of theirs that live
+ * in other people's homes.
+ *
+ * This is the function an account-deletion path calls. The platform does not
+ * have one yet (see docs/home-privacy.md), which is exactly why this is a
+ * standalone, idempotent export rather than an inline block inside a handler
+ * that does not exist: when the platform-wide path lands, it calls this.
+ *
+ * Idempotent by construction. Every statement is a delete or an update filtered
+ * on the user, so a second run finds nothing and changes nothing.
+ *
+ * @param {string} userId
+ * @param {{ email?: string|null }} [options] the account's email, so invitations
+ * addressed to it on other people's homes are removed too
+ * @returns {Promise<{ before: object, after: object, homes: number }>}
+ */
+export async function deleteAllHomeDataForUser(userId, { email = null } = {}) {
+ const before = await countUserRows(userId, email);
+
+ const homes = await sql`select id from home_connections where user_id = ${userId}`;
+ const homeIds = homes.map((h) => h.id);
+
+ if (homeIds.length) {
+ await sql`delete from audit_log where resource_id = any(${homeIds}) and action like 'home\\_%'`;
+ // One statement, one cascade: home_members, home_invites,
+ // home_entity_grants and home_action_log all hang off this row.
+ await sql`delete from home_connections where user_id = ${userId}`;
+ }
+
+ // Memberships and grants this user holds on homes they do NOT own. The grant
+ // cascade added in 20260903180000 handles grants; membership is its own row.
+ await sql`delete from home_members where user_id = ${userId}`;
+ await sql`delete from home_entity_grants where granted_by = ${userId}`;
+ await sql`delete from home_invites where invited_by = ${userId}`;
+ if (email) {
+ await sql`delete from home_invites where lower(email) = lower(${email})`;
+ }
+
+ // The action log's actor columns carry no foreign key (an actor can be an
+ // agent with no account), so nothing removes a departed user's id from
+ // another household's log. Scrub rather than delete: the household that owns
+ // those rows is entitled to its own history, and it does not need to keep a
+ // pointer to a person who left.
+ await sql`update home_action_log set user_id = null where user_id = ${userId}`;
+ await sql`update home_action_log set confirmed_by = null where confirmed_by = ${userId}`;
+
+ const after = await countUserRows(userId, email);
+ return { before, after, homes: homeIds.length };
+}
+
+/**
+ * Per-table row counts for one home. The proof behind every deletion claim in
+ * docs/home-privacy.md, and the shape a test asserts on.
+ *
+ * @param {string} homeId
+ * @returns {Promise<Record<string, number>>}
+ */
+export async function countHomeRows(homeId) {
+ const [conn, members, invites, grants, actions, audit] = await Promise.all([
+ sql`select count(*)::int as n from home_connections where id = ${homeId}`,
+ sql`select count(*)::int as n from home_members where home_id = ${homeId}`,
+ sql`select count(*)::int as n from home_invites where home_id = ${homeId}`,
+ sql`select count(*)::int as n from home_entity_grants where home_id = ${homeId}`,
+ sql`select count(*)::int as n from home_action_log where home_id = ${homeId}`,
+ sql`select count(*)::int as n from audit_log where resource_id = ${homeId} and action like 'home\\_%'`,
+ ]);
+ return {
+ home_connections: conn[0].n,
+ home_members: members[0].n,
+ home_invites: invites[0].n,
+ home_entity_grants: grants[0].n,
+ home_action_log: actions[0].n,
+ audit_log: audit[0].n,
+ };
+}
+
+/**
+ * Per-table row counts for everything one account touches, owned or not.
+ *
+ * @param {string} userId
+ * @param {string|null} [email]
+ * @returns {Promise<Record<string, number>>}
+ */
+export async function countUserRows(userId, email = null) {
+ const [conn, members, invites, invitesToEmail, grants, actorRows, confirmRows, audit] =
+ await Promise.all([
+ sql`select count(*)::int as n from home_connections where user_id = ${userId}`,
+ sql`select count(*)::int as n from home_members where user_id = ${userId}`,
+ sql`select count(*)::int as n from home_invites where invited_by = ${userId}`,
+ email
+ ? sql`select count(*)::int as n from home_invites where lower(email) = lower(${email})`
+ : Promise.resolve([{ n: 0 }]),
+ sql`select count(*)::int as n from home_entity_grants where granted_by = ${userId}`,
+ sql`select count(*)::int as n from home_action_log where user_id = ${userId}`,
+ sql`select count(*)::int as n from home_action_log where confirmed_by = ${userId}`,
+ sql`select count(*)::int as n from audit_log where action like 'home\\_%' and user_id = ${userId}`,
+ ]);
+ return {
+ home_connections: conn[0].n,
+ home_members: members[0].n,
+ home_invites_sent: invites[0].n,
+ home_invites_to_email: invitesToEmail[0].n,
+ home_entity_grants: grants[0].n,
+ home_action_log_actor: actorRows[0].n,
+ home_action_log_confirmed_by: confirmRows[0].n,
+ audit_log: audit[0].n,
+ };
+}
+
+/**
+ * The plain-language summary the privacy screen renders: what we hold about you
+ * right now, in numbers, next to the inventory that explains each one.
+ *
+ * @param {string} userId
+ * @param {string|null} [email]
+ * @returns {Promise<object>}
+ */
+export async function summarizeHomeData(userId, email = null) {
+ const [counts, homes] = await Promise.all([
+ countUserRows(userId, email),
+ withDbRetry(
+ () => sql`
+ select id, label, status, created_at, revoked_at,
+ action_log_retention_days, action_log_retention_reason
+ from home_connections
+ where user_id = ${userId}
+ order by created_at
+ `,
+ { timeoutMs: 5_000 },
+ ),
+ ]);
+ return {
+ inventory: INVENTORY,
+ counts,
+ homes,
+ retention: {
+ default_days: DEFAULT_ACTION_LOG_RETENTION_DAYS,
+ min_days: MIN_ACTION_LOG_RETENTION_DAYS,
+ max_days: MAX_ACTION_LOG_RETENTION_DAYS,
+ reason_required_above_days: DEFAULT_ACTION_LOG_RETENTION_DAYS,
+ },
+ };
+}
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.js
index ce89a51e9..cfdaed00e 100644
--- a/api/_lib/rate-limit.js
+++ b/api/_lib/rate-limit.js
@@ -2028,6 +2028,21 @@ export const limits = {
// up, which is exactly the bypass that makes an RPC cap meaningless.
printOrderIp: (ip) =>
getLimiter('print:order:ip', { limit: 60, window: '5 m' }).limit(ip),
+ // Household invitations (api/home/[id]/members.js). An invite link is a bearer
+ // credential for a role in a physical building, so the ceiling is deliberately
+ // low: 20 per hour per account is more households than anyone administers and
+ // far too few for a compromised session to spray keys with. Keyed on the
+ // account, not the IP, because the account is what the capability hangs off.
+ // NOT local: a per-instance counter would multiply the ceiling by however many
+ // Cloud Run instances are up, which is exactly the bypass that matters here.
+ homeInvite: (userId) =>
+ getLimiter('home:invite:user', { limit: 20, window: '1 h' }).limit(userId),
+ // Redeeming a household invitation (api/home/invites/[token].js). The token is
+ // 256 bits of randomness, so this is not what stops a guess; it is what makes
+ // "guessing is not feasible" a bounded statement rather than a hopeful one, and
+ // what stops an enumeration sweep from costing us a database round trip each.
+ homeInviteRedeem: (ip) =>
+ getLimiter('home:invite:redeem:ip', { limit: 30, window: '10 m' }).limit(ip),
};
// ── Fail-closed limiter call for privacy-boundary reads (H7) ─────────────────
diff --git a/packages/home-mcp/LICENSE b/packages/home-mcp/LICENSE
new file mode 100644
index 000000000..b5ae2a4e1
--- /dev/null
+++ b/packages/home-mcp/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2026 nirholas
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/packages/home-mcp/src/lib/home.js b/packages/home-mcp/src/lib/home.js
new file mode 100644
index 000000000..4dbbd429d
--- /dev/null
+++ b/packages/home-mcp/src/lib/home.js
@@ -0,0 +1,69 @@
+// The one live connection to the user's house, shared by every tool.
+//
+// A stdio MCP server is a long-lived process serving one household, so the
+// bridge is opened once on the first tool call and kept: the Home Assistant
+// socket reconnects and resubscribes on its own, so a house that goes away for
+// a minute comes back without the model noticing.
+
+import { HomeBridge, HomeBridgeError, ERR } from '@three-ws/home-bridge';
+
+let bridge = null;
+let opening = null;
+
+/** Env, read at call time so a test can set it and a shell export is honoured. */
+export function config() {
+ const baseUrl = process.env.HOME_ASSISTANT_URL || '';
+ const token = process.env.HOME_ASSISTANT_TOKEN || '';
+ const allowed = String(process.env.HOME_ALLOWED_ENTITIES || '')
+ .split(',')
+ .map((s) => s.trim())
+ .filter(Boolean);
+ return { baseUrl, token, allowed };
+}
+
+/**
+ * The bridge, connected.
+ *
+ * Missing credentials are an ordinary state with a designed answer, not a
+ * stack trace: the operator has not told the server which house to talk to.
+ */
+export async function home() {
+ if (bridge?.connected) return bridge;
+ if (opening) return opening;
+
+ const { baseUrl, token, allowed } = config();
+ if (!baseUrl) {
+ throw new HomeBridgeError(
+ ERR.BAD_URL,
+ 'HOME_ASSISTANT_URL is not set. Point it at the https URL of your Home Assistant (Home Assistant Cloud, or your own reverse proxy).',
+ );
+ }
+ if (!token) {
+ throw new HomeBridgeError(
+ ERR.AUTH,
+ 'HOME_ASSISTANT_TOKEN is not set. Create a long-lived access token in Home Assistant under your profile, Security, Long-lived access tokens.',
+ );
+ }
+
+ opening = (async () => {
+ const next = new HomeBridge({ baseUrl, token, allowedEntities: allowed });
+ await next.connect();
+ bridge = next;
+ opening = null;
+ return next;
+ })();
+
+ try {
+ return await opening;
+ } catch (err) {
+ opening = null;
+ throw err;
+ }
+}
+
+/** Close the socket. Used by the process exit path and by the tests. */
+export function closeHome() {
+ bridge?.close();
+ bridge = null;
+ opening = null;
+}
diff --git a/scripts/home-fleet.mjs b/scripts/home-fleet.mjs
index 391695214..fdaac23a5 100644
--- a/scripts/home-fleet.mjs
+++ b/scripts/home-fleet.mjs
@@ -57,6 +57,20 @@ function run(cmd, args, { capture = true } = {}) {
const docker = (...args) => run('docker', args);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Home Assistant runs as root inside the container and writes root-owned files
+ * into the bind-mounted config directory (blueprints, .storage, the database),
+ * so the host user cannot unlink them. Deleting them therefore has to happen as
+ * root too, and the cheapest root on this machine is the image we already have.
+ */
+async function removeAsRoot(target) {
+ const parent = path.dirname(target);
+ const leaf = path.basename(target);
+ await mkdir(parent, { recursive: true });
+ await docker('run', '--rm', '-v', `${parent}:/scrub`, '--entrypoint', 'rm', IMAGE, '-rf', `/scrub/${leaf}`).catch(() => null);
+ await rm(target, { recursive: true, force: true }).catch(() => null);
+}
+
// ---------------------------------------------------------------- configuration
/**
@@ -267,7 +281,7 @@ async function seedRegistry(send) {
}
async function mintLongLivedToken(send, clientName) {
- return send({ type: 'auth/long_lived_access_token', client_name: clientName, client_icon: null, lifespan: 3650 });
+ return send({ type: 'auth/long_lived_access_token', client_name: clientName, lifespan: 3650 });
}
// ---------------------------------------------------------------- latency shim
@@ -320,7 +334,7 @@ async function startHouse({ index, big }) {
const configDir = path.join(CONFIG_ROOT, String(index));
await docker('rm', '-f', name).catch(() => null);
- await rm(configDir, { recursive: true, force: true });
+ await removeAsRoot(configDir);
await mkdir(configDir, { recursive: true });
await writeFile(path.join(configDir, 'configuration.yaml'), configurationYaml({ big }));
await writeFile(path.join(configDir, 'automations.yaml'), '[]\n');
@@ -408,7 +422,7 @@ async function down() {
await docker('rm', '-f', name).catch(() => null);
console.log(` removed ${name}`);
}
- await rm(CONFIG_ROOT, { recursive: true, force: true });
+ await removeAsRoot(CONFIG_ROOT);
await rm(MANIFEST, { force: true });
console.log(containers.length ? `\n${containers.length} container(s) removed` : 'nothing running');
}
diff --git a/services/home-relay/Dockerfile b/services/home-relay/Dockerfile
new file mode 100644
index 000000000..68c61553a
--- /dev/null
+++ b/services/home-relay/Dockerfile
@@ -0,0 +1,11 @@
+FROM node:22-alpine
+WORKDIR /app
+# Copy the lockfile too: `npm ci` installs the exact tree this service is tested
+# against, instead of silently resolving newer minors at image-build time.
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+COPY src ./src
+COPY allowlist.json ./allowlist.json
+ENV NODE_ENV=production
+EXPOSE 8080
+CMD ["node", "src/index.js"]
diff --git a/services/home-relay/allowlist.json b/services/home-relay/allowlist.json
new file mode 100644
index 000000000..3be138ff7
--- /dev/null
+++ b/services/home-relay/allowlist.json
@@ -0,0 +1,65 @@
+{
+ "protocolVersion": 1,
+ "minAgentProtocol": 1,
+ "frameTypes": [
+ "hello",
+ "hello.ok",
+ "hello.err",
+ "ping",
+ "pong",
+ "session.open",
+ "session.ready",
+ "session.close",
+ "ha"
+ ],
+ "outboundTypes": [
+ "supported_features",
+ "get_states",
+ "get_config",
+ "subscribe_entities",
+ "subscribe_events",
+ "unsubscribe_events",
+ "ping",
+ "config/floor_registry/list",
+ "config/area_registry/list",
+ "config/device_registry/list",
+ "config/entity_registry/list",
+ "call_service"
+ ],
+ "inboundTypes": [
+ "result",
+ "event",
+ "pong"
+ ],
+ "allowedEventTypes": [
+ "state_changed"
+ ],
+ "deniedServiceDomains": [
+ "shell_command",
+ "python_script",
+ "hassio",
+ "supervisor",
+ "backup",
+ "update",
+ "cloud",
+ "config",
+ "auth",
+ "command_line"
+ ],
+ "deniedServices": [
+ "homeassistant.restart",
+ "homeassistant.stop",
+ "homeassistant.check_config",
+ "homeassistant.reload_all",
+ "homeassistant.reload_core_config",
+ "persistent_notification.create"
+ ],
+ "limits": {
+ "maxFrameBytes": 4194304,
+ "maxSessionsPerInstall": 8,
+ "outboundFramesPerSecond": 40,
+ "serviceCallsPerMinute": 60,
+ "heartbeatMs": 25000,
+ "heartbeatTimeoutMs": 60000
+ }
+}
diff --git a/services/home-relay/package-lock.json b/services/home-relay/package-lock.json
new file mode 100644
index 000000000..6ff7f9e41
--- /dev/null
+++ b/services/home-relay/package-lock.json
@@ -0,0 +1,39 @@
+{
+ "name": "home-relay",
+ "version": "1.0.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "home-relay",
+ "version": "1.0.0",
+ "dependencies": {
+ "ws": "^8.21.0"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ },
+ "node_modules/ws": {
+ "version": "8.21.3",
+ "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
+ "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=10.0.0"
+ },
+ "peerDependencies": {
+ "bufferutil": "^4.0.1",
+ "utf-8-validate": ">=5.0.2"
+ },
+ "peerDependenciesMeta": {
+ "bufferutil": {
+ "optional": true
+ },
+ "utf-8-validate": {
+ "optional": true
+ }
+ }
+ }
+ }
+}
diff --git a/services/home-relay/package.json b/services/home-relay/package.json
new file mode 100644
index 000000000..845db4245
--- /dev/null
+++ b/services/home-relay/package.json
@@ -0,0 +1,18 @@
+{
+ "name": "home-relay",
+ "version": "1.0.0",
+ "private": true,
+ "description": "Terminates the outbound WebSocket that a three.ws Home Assistant integration dials from inside a LAN-only house, and multiplexes allowlisted platform requests onto it.",
+ "type": "module",
+ "main": "src/index.js",
+ "scripts": {
+ "start": "node src/index.js",
+ "build:allowlist": "node scripts/gen-allowlist.mjs"
+ },
+ "engines": {
+ "node": ">=20"
+ },
+ "dependencies": {
+ "ws": "^8.21.0"
+ }
+}
diff --git a/services/home-relay/scripts/gen-allowlist.mjs b/services/home-relay/scripts/gen-allowlist.mjs
new file mode 100644
index 000000000..8e27c25f5
--- /dev/null
+++ b/services/home-relay/scripts/gen-allowlist.mjs
@@ -0,0 +1,21 @@
+/**
+ * Writes services/home-relay/allowlist.json from src/protocol.js.
+ *
+ * The relay enforces the allowlist in JavaScript and the Home Assistant
+ * integration enforces it again in Python. Two enforcement points that drift
+ * apart would be worse than one, so the Python side reads this generated file
+ * rather than transcribing the rules, and tests/home-relay-protocol.test.js
+ * fails if this file is stale.
+ *
+ * node services/home-relay/scripts/gen-allowlist.mjs
+ */
+
+import { writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { allowlistManifest } from '../src/protocol.js';
+
+const out = join(dirname(fileURLToPath(import.meta.url)), '..', 'allowlist.json');
+writeFileSync(out, `${JSON.stringify(allowlistManifest(), null, '\t')}\n`);
+console.log(`wrote ${out}`);
diff --git a/services/home-relay/src/index.js b/services/home-relay/src/index.js
new file mode 100644
index 000000000..e7c9316ce
--- /dev/null
+++ b/services/home-relay/src/index.js
@@ -0,0 +1,26 @@
+/**
+ * Cloud Run entry point for the three.ws home relay.
+ *
+ * The relay is a long-lived WebSocket terminator, so it deploys with
+ * --no-cpu-throttling and a min instance count: a house's dial-out socket has
+ * to survive between platform requests, and a throttled container would let it
+ * die and reconnect in a loop. See cloudbuild.yaml.
+ */
+
+import { createRelay } from './server.js';
+
+const port = Number(process.env.PORT || 8080);
+const relay = createRelay();
+
+const address = await relay.listen(port);
+console.log(JSON.stringify({ event: 'relay.listening', port: address.port }));
+
+// Cloud Run sends SIGTERM before it takes an instance away. Closing the sockets
+// ourselves tells every house to reconnect immediately instead of leaving them
+// waiting out a heartbeat timeout against a container that is already gone.
+for (const signal of ['SIGTERM', 'SIGINT']) {
+ process.on(signal, () => {
+ console.log(JSON.stringify({ event: 'relay.shutdown', signal, ...relay.stats() }));
+ relay.close().then(() => process.exit(0), () => process.exit(1));
+ });
+}
diff --git a/services/home-relay/src/server.js b/services/home-relay/src/server.js
new file mode 100644
index 000000000..c9df8cca3
--- /dev/null
+++ b/services/home-relay/src/server.js
@@ -0,0 +1,470 @@
+/**
+ * The three.ws home relay.
+ *
+ * A house that only exists on a LAN cannot be reached from Cloud Run, so the
+ * house dials out instead: the three.ws integration inside Home Assistant opens
+ * one outbound WebSocket to this service and keeps it. The platform then asks
+ * this service to open a session over that socket. Nothing listens on the
+ * user's network, no port is forwarded, and no inbound firewall rule exists.
+ *
+ * This service is deliberately small and deliberately dumb:
+ *
+ * * It holds no database. Ownership is proved by the signature on the install
+ * token the house presents (`token.js`), so the connect path never queries
+ * anything.
+ * * It holds no Home Assistant credential, ever. Authentication happens
+ * locally inside the house and never crosses this process.
+ * * It forwards only the message types in `protocol.js`, in the direction
+ * that protocol permits, and the integration enforces the same list again
+ * at the far end so that compromising this service does not compromise a
+ * house.
+ *
+ * Read `docs/home-relay-threat-model.md` before changing anything here.
+ */
+
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+
+import { CODE, FRAME, LIMITS, checkInbound, checkOutbound, decodeFrame, encodeFrame, frames, negotiate } from './protocol.js';
+import { constantTimeEquals, verifyInstallToken } from './token.js';
+
+const SERVICE_VERSION = '1.0.0';
+
+/**
+ * A token bucket. Used per install for both frame rate and actuation rate,
+ * because a bug in an integration must not be able to flood a house and a
+ * compromised platform caller must not be able to hammer a lock.
+ */
+class Bucket {
+ constructor(capacity, refillPerSecond) {
+ this.capacity = capacity;
+ this.refillPerSecond = refillPerSecond;
+ this.tokens = capacity;
+ this.last = Date.now();
+ }
+
+ take(now = Date.now()) {
+ const elapsed = Math.max(0, now - this.last) / 1000;
+ this.last = now;
+ this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillPerSecond);
+ if (this.tokens < 1) return false;
+ this.tokens -= 1;
+ return true;
+ }
+}
+
+/** One dialled-in house. */
+class Install {
+ constructor(relayId, socket, claims, agentInfo) {
+ this.relayId = relayId;
+ this.socket = socket;
+ this.claims = claims;
+ this.agent = agentInfo;
+ this.connectedAt = Date.now();
+ this.sessions = new Map();
+ this.frameBucket = new Bucket(LIMITS.outboundFramesPerSecond, LIMITS.outboundFramesPerSecond);
+ this.callBucket = new Bucket(LIMITS.serviceCallsPerMinute, LIMITS.serviceCallsPerMinute / 60);
+ this.alive = true;
+ this.counters = { framesIn: 0, framesOut: 0, denied: 0, sessions: 0 };
+ }
+
+ send(frame) {
+ if (this.socket.readyState !== this.socket.OPEN) return false;
+ this.socket.send(encodeFrame(frame));
+ this.counters.framesOut += 1;
+ return true;
+ }
+}
+
+export function createRelay(options = {}) {
+ const signingKey = options.signingKey || process.env.HOME_RELAY_SIGNING_KEY;
+ const serviceToken = options.serviceToken || process.env.HOME_RELAY_SERVICE_TOKEN;
+ if (!signingKey || signingKey.length < 32) throw new Error('HOME_RELAY_SIGNING_KEY must be set to at least 32 characters.');
+ if (!serviceToken || serviceToken.length < 32) throw new Error('HOME_RELAY_SERVICE_TOKEN must be set to at least 32 characters.');
+ const log = options.log || ((event, fields) => console.log(JSON.stringify({ event, ...fields })));
+
+ /** relayId to Install. One socket per house: a second dial-in replaces the first. */
+ const installs = new Map();
+ /** relayId to the epoch ms it was revoked, so a race cannot re-register it. */
+ const revoked = new Map();
+ const startedAt = Date.now();
+
+ const server = createServer((req, res) => handleHttp(req, res));
+ const agentWss = new WebSocketServer({ noServer: true, maxPayload: LIMITS.maxFrameBytes });
+ const bridgeWss = new WebSocketServer({ noServer: true, maxPayload: LIMITS.maxFrameBytes });
+
+ server.on('upgrade', (req, socket, head) => {
+ let url;
+ try {
+ url = new URL(req.url, 'http://relay.invalid');
+ } catch {
+ return refuseUpgrade(socket, 400, 'Bad request');
+ }
+ if (url.pathname === '/v1/agent') {
+ const auth = bearer(req);
+ const verdict = verifyInstallToken(auth, signingKey);
+ if (!verdict.ok) {
+ log('agent.rejected', { reason: verdict.reason });
+ return refuseUpgrade(socket, 401, 'Unauthorized');
+ }
+ if (revoked.has(verdict.claims.relayId)) {
+ log('agent.rejected', { relayId: verdict.claims.relayId, reason: 'revoked' });
+ return refuseUpgrade(socket, 403, 'Revoked');
+ }
+ return agentWss.handleUpgrade(req, socket, head, (ws) => onAgent(ws, verdict.claims));
+ }
+ if (url.pathname === '/v1/bridge') {
+ if (!constantTimeEquals(bearer(req), serviceToken)) {
+ log('bridge.rejected', { reason: 'bad service token' });
+ return refuseUpgrade(socket, 401, 'Unauthorized');
+ }
+ const relayId = url.searchParams.get('relay_id') || '';
+ return bridgeWss.handleUpgrade(req, socket, head, (ws) => onBridge(ws, relayId));
+ }
+ return refuseUpgrade(socket, 404, 'Not found');
+ });
+
+ // ---------------------------------------------------------------- the house
+
+ function onAgent(ws, claims) {
+ const { relayId } = claims;
+ let install = null;
+ let helloTimer = setTimeout(() => {
+ if (!install) {
+ ws.send(encodeFrame(frames.helloErr(CODE.MALFORMED, 'No hello frame within 10 seconds.')));
+ ws.close(4000, CODE.MALFORMED);
+ }
+ }, 10_000);
+
+ ws.on('message', (raw) => {
+ const decoded = decodeFrame(raw);
+ if (!decoded.ok) {
+ log('agent.malformed', { relayId, reason: decoded.message });
+ ws.close(4000, decoded.code);
+ return;
+ }
+ const frame = decoded.frame;
+
+ if (!install) {
+ if (frame.t !== FRAME.HELLO) {
+ ws.send(encodeFrame(frames.helloErr(CODE.MALFORMED, 'The first frame must be hello.')));
+ ws.close(4000, CODE.MALFORMED);
+ return;
+ }
+ const agreed = negotiate(frame.protocol);
+ if (!agreed.ok) {
+ log('agent.protocol', { relayId, code: agreed.code });
+ ws.send(encodeFrame(frames.helloErr(agreed.code, agreed.message)));
+ ws.close(4001, agreed.code);
+ return;
+ }
+ if (revoked.has(relayId)) {
+ ws.send(encodeFrame(frames.helloErr(CODE.REVOKED, 'This home was disconnected in three.ws. Remove and re-add the integration to pair it again.')));
+ ws.close(4003, CODE.REVOKED);
+ return;
+ }
+ clearTimeout(helloTimer);
+ helloTimer = null;
+ // One house, one socket. A stale socket from a crashed container
+ // would otherwise shadow the live one forever.
+ const previous = installs.get(relayId);
+ if (previous && previous.socket !== ws) {
+ closeInstall(previous, CODE.GOING_AWAY, 'Replaced by a newer connection from this home.');
+ }
+ install = new Install(relayId, ws, claims, sanitizeAgentInfo(frame.agent));
+ installs.set(relayId, install);
+ ws.send(encodeFrame(frames.helloOk(relayId, { version: SERVICE_VERSION })));
+ log('agent.online', { relayId, agent: install.agent, protocol: agreed.protocol });
+ return;
+ }
+
+ install.counters.framesIn += 1;
+ routeFromAgent(install, frame);
+ });
+
+ ws.on('pong', () => {
+ if (install) install.alive = true;
+ });
+
+ ws.on('close', () => {
+ if (helloTimer) clearTimeout(helloTimer);
+ if (install && installs.get(relayId) === install) {
+ installs.delete(relayId);
+ for (const session of install.sessions.values()) {
+ session.bridge.send(encodeFrame(frames.sessionClose(session.sid, CODE.AGENT_OFFLINE, 'The three.ws integration in this home went offline.')));
+ session.bridge.close(1000, CODE.AGENT_OFFLINE);
+ }
+ install.sessions.clear();
+ log('agent.offline', { relayId, uptimeMs: Date.now() - install.connectedAt, counters: install.counters });
+ }
+ });
+
+ ws.on('error', (err) => log('agent.error', { relayId, message: err?.message }));
+ }
+
+ function routeFromAgent(install, frame) {
+ if (frame.t === FRAME.PONG || frame.t === FRAME.PING) {
+ if (frame.t === FRAME.PING) install.send(frames.pong(frame.ts));
+ return;
+ }
+ const session = install.sessions.get(frame.sid);
+ if (!session) return; // A reply for a session the platform already dropped.
+
+ if (frame.t === FRAME.SESSION_READY) {
+ session.ready = true;
+ session.bridge.send(encodeFrame(frames.sessionReady(session.sid, String(frame.haVersion || ''))));
+ return;
+ }
+ if (frame.t === FRAME.SESSION_CLOSE) {
+ session.bridge.send(encodeFrame(frames.sessionClose(session.sid, String(frame.code || CODE.OK), String(frame.reason || ''))));
+ session.bridge.close(1000, String(frame.code || CODE.OK));
+ return;
+ }
+ if (frame.t === FRAME.HA) {
+ const verdict = checkInbound(frame.msg);
+ if (!verdict.allowed) {
+ install.counters.denied += 1;
+ log('relay.denied', { relayId: install.relayId, direction: 'inbound', code: verdict.code, reason: verdict.reason });
+ return;
+ }
+ session.bridge.send(encodeFrame(frames.ha(session.sid, frame.msg)));
+ }
+ }
+
+ // ------------------------------------------------------------- the platform
+
+ function onBridge(ws, relayId) {
+ const install = installs.get(relayId);
+ if (!relayId || !install) {
+ ws.send(encodeFrame(frames.sessionClose('pending', CODE.AGENT_OFFLINE, 'No three.ws integration is connected for this home right now.')));
+ ws.close(1000, CODE.AGENT_OFFLINE);
+ return;
+ }
+ if (install.sessions.size >= LIMITS.maxSessionsPerInstall) {
+ ws.send(encodeFrame(frames.sessionClose('pending', CODE.TOO_MANY_SESSIONS, `This home already has ${install.sessions.size} open sessions.`)));
+ ws.close(1000, CODE.TOO_MANY_SESSIONS);
+ return;
+ }
+
+ const sid = `s_${randomBytes(9).toString('base64url')}`;
+ const session = { sid, bridge: ws, install, ready: false, openedAt: Date.now() };
+ install.sessions.set(sid, session);
+ install.counters.sessions += 1;
+ install.send(frames.sessionOpen(sid));
+ log('session.open', { relayId, sid });
+
+ ws.on('message', (raw) => {
+ const decoded = decodeFrame(raw);
+ if (!decoded.ok) {
+ ws.send(encodeFrame(frames.sessionClose(sid, decoded.code, decoded.message)));
+ ws.close(4000, decoded.code);
+ return;
+ }
+ const frame = decoded.frame;
+ if (frame.t === FRAME.SESSION_CLOSE) {
+ ws.close(1000, CODE.OK);
+ return;
+ }
+ if (frame.t !== FRAME.HA) return;
+
+ if (!install.frameBucket.take()) {
+ install.counters.denied += 1;
+ log('relay.rate_limited', { relayId, kind: 'frames' });
+ replyRefusal(ws, sid, frame.msg, CODE.RATE_LIMITED, 'Too many requests into this home. Slow down.');
+ return;
+ }
+ const verdict = checkOutbound(frame.msg);
+ if (!verdict.allowed) {
+ install.counters.denied += 1;
+ log('relay.denied', { relayId, direction: 'outbound', code: verdict.code, reason: verdict.reason, type: typeof frame.msg?.type === 'string' ? frame.msg.type.slice(0, 64) : null });
+ replyRefusal(ws, sid, frame.msg, verdict.code, verdict.reason);
+ return;
+ }
+ if (frame.msg.type === 'call_service' && !install.callBucket.take()) {
+ install.counters.denied += 1;
+ log('relay.rate_limited', { relayId, kind: 'call_service' });
+ replyRefusal(ws, sid, frame.msg, CODE.RATE_LIMITED, 'Too many service calls into this home in the last minute.');
+ return;
+ }
+ install.send(frames.ha(sid, frame.msg));
+ });
+
+ ws.on('close', () => {
+ if (install.sessions.get(sid) === session) {
+ install.sessions.delete(sid);
+ install.send(frames.sessionClose(sid, CODE.OK, 'The platform closed this session.'));
+ log('session.close', { relayId, sid, ms: Date.now() - session.openedAt });
+ }
+ });
+
+ ws.on('error', (err) => log('bridge.error', { relayId, sid, message: err?.message }));
+ }
+
+ /**
+ * A refused frame gets a Home Assistant shaped error result rather than a
+ * dropped connection, so the client's own promise rejects with a real
+ * message instead of hanging until its timeout. The session survives: one
+ * bad call is not a reason to tear down a live house.
+ */
+ function replyRefusal(ws, sid, msg, code, reason) {
+ const id = Number.isInteger(msg?.id) ? msg.id : null;
+ if (id === null) return;
+ ws.send(encodeFrame(frames.ha(sid, { id, type: 'result', success: false, error: { code, message: reason } })));
+ }
+
+ // ------------------------------------------------------------------- admin
+
+ function handleHttp(req, res) {
+ const url = new URL(req.url || '/', 'http://relay.invalid');
+ if (req.method === 'GET' && (url.pathname === '/healthz' || url.pathname === '/')) {
+ return sendJson(res, 200, {
+ ok: true,
+ service: 'home-relay',
+ version: SERVICE_VERSION,
+ uptimeSeconds: Math.round((Date.now() - startedAt) / 1000),
+ installs: installs.size,
+ sessions: [...installs.values()].reduce((n, i) => n + i.sessions.size, 0),
+ });
+ }
+ if (!constantTimeEquals(bearer(req), serviceToken)) return sendJson(res, 401, { error: 'unauthorized' });
+
+ if (req.method === 'GET' && url.pathname === '/v1/status') {
+ const relayId = url.searchParams.get('relay_id');
+ if (relayId) {
+ const install = installs.get(relayId);
+ return sendJson(res, 200, { relayId, online: Boolean(install), ...(install ? describeInstall(install) : { revokedAt: revoked.get(relayId) || null }) });
+ }
+ return sendJson(res, 200, { installs: [...installs.values()].map((i) => ({ relayId: i.relayId, ...describeInstall(i) })) });
+ }
+ if (req.method === 'POST' && url.pathname === '/v1/revoke') {
+ return readJson(req, (body) => {
+ const relayId = body?.relayId;
+ if (typeof relayId !== 'string' || !relayId) return sendJson(res, 400, { error: 'relayId is required' });
+ revoked.set(relayId, Date.now());
+ const install = installs.get(relayId);
+ if (install) closeInstall(install, CODE.REVOKED, 'This home was disconnected in three.ws.');
+ log('relay.revoked', { relayId, wasOnline: Boolean(install) });
+ return sendJson(res, 200, { relayId, revoked: true, wasOnline: Boolean(install) });
+ }, res);
+ }
+ if (req.method === 'POST' && url.pathname === '/v1/unrevoke') {
+ return readJson(req, (body) => {
+ const relayId = body?.relayId;
+ if (typeof relayId !== 'string' || !relayId) return sendJson(res, 400, { error: 'relayId is required' });
+ const had = revoked.delete(relayId);
+ log('relay.unrevoked', { relayId, had });
+ return sendJson(res, 200, { relayId, revoked: false });
+ }, res);
+ }
+ return sendJson(res, 404, { error: 'not found' });
+ }
+
+ function describeInstall(install) {
+ return {
+ agent: install.agent,
+ connectedAt: new Date(install.connectedAt).toISOString(),
+ sessions: install.sessions.size,
+ counters: { ...install.counters },
+ };
+ }
+
+ function closeInstall(install, code, reason) {
+ for (const session of install.sessions.values()) {
+ try {
+ session.bridge.send(encodeFrame(frames.sessionClose(session.sid, code, reason)));
+ session.bridge.close(1000, code);
+ } catch {
+ // A bridge socket that is already gone needs no further closing.
+ }
+ }
+ install.sessions.clear();
+ if (installs.get(install.relayId) === install) installs.delete(install.relayId);
+ try {
+ install.socket.send(encodeFrame(frames.sessionClose('all', code, reason)));
+ install.socket.close(4003, code);
+ } catch {
+ // Same: the socket may already be dead, which is the outcome we wanted.
+ }
+ }
+
+ // --------------------------------------------------------------- heartbeat
+
+ const heartbeat = setInterval(() => {
+ for (const install of installs.values()) {
+ if (!install.alive) {
+ log('agent.timeout', { relayId: install.relayId });
+ install.socket.terminate();
+ continue;
+ }
+ install.alive = false;
+ try {
+ install.socket.ping();
+ } catch {
+ install.socket.terminate();
+ }
+ }
+ }, LIMITS.heartbeatMs);
+ heartbeat.unref?.();
+
+ return {
+ server,
+ installs,
+ revoked,
+ stats: () => ({
+ installs: installs.size,
+ sessions: [...installs.values()].reduce((n, i) => n + i.sessions.size, 0),
+ revoked: revoked.size,
+ }),
+ listen: (port, host = '0.0.0.0') => new Promise((resolve) => server.listen(port, host, () => resolve(server.address()))),
+ close: async () => {
+ clearInterval(heartbeat);
+ for (const install of [...installs.values()]) closeInstall(install, CODE.GOING_AWAY, 'The relay is shutting down.');
+ agentWss.close();
+ bridgeWss.close();
+ await new Promise((resolve) => server.close(resolve));
+ },
+ };
+}
+
+function sanitizeAgentInfo(agent) {
+ if (!agent || typeof agent !== 'object') return { name: 'unknown', version: 'unknown' };
+ const trim = (value, max) => (typeof value === 'string' ? value.slice(0, max) : 'unknown');
+ return { name: trim(agent.name, 64), version: trim(agent.version, 32), ha: trim(agent.ha, 32) };
+}
+
+function bearer(req) {
+ const header = req.headers?.authorization || '';
+ return header.startsWith('Bearer ') ? header.slice(7) : '';
+}
+
+function refuseUpgrade(socket, status, text) {
+ socket.write(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\n\r\n`);
+ socket.destroy();
+}
+
+function sendJson(res, status, body) {
+ const payload = JSON.stringify(body);
+ res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
+ res.end(payload);
+}
+
+function readJson(req, onBody, res) {
+ const chunks = [];
+ let size = 0;
+ req.on('data', (chunk) => {
+ size += chunk.length;
+ if (size > 64 * 1024) {
+ req.destroy();
+ return;
+ }
+ chunks.push(chunk);
+ });
+ req.on('end', () => {
+ try {
+ onBody(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'));
+ } catch {
+ sendJson(res, 400, { error: 'body must be JSON' });
+ }
+ });
+}
diff --git a/src/voice/wake-word.js b/src/voice/wake-word.js
new file mode 100644
index 000000000..857026cae
--- /dev/null
+++ b/src/voice/wake-word.js
@@ -0,0 +1,395 @@
+/**
+ * Wake-word detection in the browser, on openWakeWord's pre-trained models.
+ *
+ * openWakeWord (Apache-2.0, https://github.com/dscripka/openWakeWord) publishes
+ * both the models and the exact inference graph they were trained against. This
+ * module runs that graph with onnxruntime-web; it does not invent a detector,
+ * and it does not train one. The models are committed under
+ * /public/models/voice/wake-word from the upstream v0.5.1 release, so detection
+ * runs entirely on the listener's own machine against bytes served by three.ws.
+ *
+ * The pipeline, which is upstream's and must stay upstream's or the trained
+ * weights stop meaning anything:
+ *
+ * 16 kHz mono audio, int16 scale
+ * -> melspectrogram.onnx every 80 ms chunk, over the last 1760 samples,
+ * giving 8 new mel frames of 32 bins (10 ms hop)
+ * -> (mel / 10) + 2 upstream's transform, not a normalisation we chose
+ * -> embedding_model.onnx a 76-frame (760 ms) window -> one 96-d embedding
+ * -> <wake word>.onnx the last 16 embeddings (1.96 s) -> one score
+ *
+ * One score per 80 ms chunk. A word therefore resolves within one chunk boundary
+ * of its final phoneme plus inference, which is what keeps detection inside the
+ * loop's 200 ms budget.
+ *
+ * Privacy, stated where the code is rather than only in the consent copy: every
+ * byte above stays in this tab. Nothing is uploaded, nothing is buffered to
+ * disk, and the ring buffers hold under two seconds of audio that is overwritten
+ * continuously. Audio only leaves the device after a detection, and then only
+ * the utterance that follows it.
+ */
+
+import { log } from '../shared/log.js';
+import { now } from './vad.js';
+
+/** Where the committed openWakeWord models are served from. */
+const MODEL_PATH = '/models/voice/wake-word/';
+/** Shared with the VAD so both runtimes fetch one copy of the wasm. */
+const RUNTIME_PATH = '/models/voice/runtime/';
+
+/** Upstream's framing, in samples at 16 kHz. Changing any of these breaks the weights. */
+const CHUNK_SAMPLES = 1280; // 80 ms: one score per chunk
+const MEL_HOP_SAMPLES = 160; // 10 ms per mel frame
+const MEL_CONTEXT_SAMPLES = 480; // the model's own lookback, so a chunk yields 8 frames
+const MEL_BINS = 32;
+const EMBEDDING_WINDOW_FRAMES = 76; // 760 ms of mel frames per embedding
+const EMBEDDING_DIMS = 96;
+const PREDICTION_EMBEDDINGS = 16; // 1.96 s of context per score
+
+/** int16 scale: the models were trained on int16 audio, not on [-1, 1] floats. */
+const INT16_SCALE = 32767;
+
+/**
+ * Upstream's default. Raising it costs misses, lowering it costs false wakes, and
+ * a false wake on an always-on mic is the more expensive of the two: it opens a
+ * capture the user did not ask for.
+ */
+export const DEFAULT_THRESHOLD = 0.5;
+
+/**
+ * How long detection stays closed after a wake. Long enough that the trailing
+ * audio of the wake word itself cannot score twice, short enough that a user who
+ * was ignored can simply say it again.
+ */
+const REFRACTORY_MS = 1500;
+
+/**
+ * The wake words shipped with the product. Every one is a pre-trained upstream
+ * model: we offer a choice among what exists rather than training a phrase of our
+ * own, because a custom phrase trained on synthetic speech would be measurably
+ * worse than these and the user would pay for it in false wakes.
+ */
+export const WAKE_WORDS = [
+ {
+ id: 'hey_jarvis',
+ file: 'hey_jarvis_v0.1.onnx',
+ phrase: 'Hey Jarvis',
+ hint: 'Two syllables and an uncommon name, so it survives a noisy kitchen best.',
+ },
+ {
+ id: 'hey_mycroft',
+ file: 'hey_mycroft_v0.1.onnx',
+ phrase: 'Hey Mycroft',
+ hint: 'The Mycroft project phrase. Rare enough in conversation to rarely misfire.',
+ },
+ {
+ id: 'alexa',
+ file: 'alexa_v0.1.onnx',
+ phrase: 'Alexa',
+ hint: 'Pick this only if no Echo is in earshot: it will wake both.',
+ },
+ {
+ id: 'hey_rhasspy',
+ file: 'hey_rhasspy_v0.1.onnx',
+ phrase: 'Hey Rhasspy',
+ hint: 'The Rhasspy phrase, and the smallest model of the four.',
+ },
+];
+
+export const DEFAULT_WAKE_WORD = 'hey_jarvis';
+
+/** @param {string} id */
+export function wakeWordById(id) {
+ return WAKE_WORDS.find((w) => w.id === id) || WAKE_WORDS.find((w) => w.id === DEFAULT_WAKE_WORD);
+}
+
+let ortPromise = null;
+
+/** Load onnxruntime-web once, on demand, pointed at our own wasm. */
+async function loadOrt() {
+ if (!ortPromise) {
+ ortPromise = import('onnxruntime-web/wasm').then((ort) => {
+ ort.env.wasm.wasmPaths = RUNTIME_PATH;
+ ort.env.wasm.numThreads = 1;
+ ort.env.logLevel = 'error';
+ return ort;
+ });
+ }
+ return ortPromise;
+}
+
+/**
+ * A fixed-length ring of rows, oldest first. Small enough to be obvious and
+ * allocation-free in the steady state, which matters on a wall display that runs
+ * for weeks.
+ */
+class RowRing {
+ constructor(rows, cols) {
+ this.rows = rows;
+ this.cols = cols;
+ this.data = new Float32Array(rows * cols);
+ this.filled = 0;
+ }
+
+ push(row) {
+ if (this.filled < this.rows) {
+ this.data.set(row, this.filled * this.cols);
+ this.filled++;
+ return;
+ }
+ this.data.copyWithin(0, this.cols);
+ this.data.set(row, (this.rows - 1) * this.cols);
+ }
+
+ get full() {
+ return this.filled >= this.rows;
+ }
+
+ /** A copy of the whole ring, oldest first. Only called once per 80 ms. */
+ snapshot() {
+ return this.data.slice(0, this.filled * this.cols);
+ }
+
+ reset() {
+ this.filled = 0;
+ this.data.fill(0);
+ }
+}
+
+export class WakeWordDetector {
+ /**
+ * @param {object} opts
+ * @param {string} [opts.wakeWord] Id from WAKE_WORDS.
+ * @param {number} [opts.threshold] Score above which a wake fires.
+ * @param {(detection: {score:number, latencyMs:number, wakeWord:string}) => void} [opts.onWake]
+ * @param {(score: number) => void} [opts.onScore] Every 80 ms score, for a live meter.
+ */
+ constructor({ wakeWord = DEFAULT_WAKE_WORD, threshold = DEFAULT_THRESHOLD, onWake, onScore } = {}) {
+ this.definition = wakeWordById(wakeWord);
+ this.threshold = threshold;
+ this.onWake = onWake || (() => {});
+ this.onScore = onScore || (() => {});
+
+ this._mel = null;
+ this._embed = null;
+ this._model = null;
+ this._ort = null;
+ this._loading = null;
+
+ // 1760 samples is all the raw audio the melspectrogram ever reads.
+ this._raw = new Float32Array(CHUNK_SAMPLES + MEL_CONTEXT_SAMPLES);
+ this._rawFilled = 0;
+ this._pending = new Float32Array(CHUNK_SAMPLES);
+ this._pendingLength = 0;
+
+ this._melRing = new RowRing(EMBEDDING_WINDOW_FRAMES, MEL_BINS);
+ this._featureRing = new RowRing(PREDICTION_EMBEDDINGS, EMBEDDING_DIMS);
+
+ this._inflight = false;
+ this._lastWakeAt = 0;
+ this._above = false;
+ /**
+ * When true, scores are still computed but no wake is emitted. The loop
+ * raises this while the agent's own voice is playing, which is the whole
+ * self-trigger guard: an agent that says its own wake word must not wake
+ * itself, and echo cancellation alone does not guarantee that on a laptop
+ * speaker at volume.
+ */
+ this.suppressed = false;
+ /** The highest score seen while suppressed, so the guard is measurable. */
+ this.suppressedPeak = 0;
+ /** Wall clock of the most recent frame handed in, for the wake latency. */
+ this._lastFrameAt = 0;
+ this.lastScore = 0;
+ }
+
+ get ready() {
+ return !!this._model;
+ }
+
+ get wakeWord() {
+ return this.definition.id;
+ }
+
+ /** Fetch and compile the three models. Safe to call more than once. */
+ async load() {
+ if (this._model) return;
+ if (!this._loading) this._loading = this._load();
+ await this._loading;
+ }
+
+ async _load() {
+ const ort = await loadOrt();
+ this._ort = ort;
+ const opts = { executionProviders: ['wasm'] };
+ const [mel, embed, model] = await Promise.all([
+ ort.InferenceSession.create(`${MODEL_PATH}melspectrogram.onnx`, opts),
+ ort.InferenceSession.create(`${MODEL_PATH}embedding_model.onnx`, opts),
+ ort.InferenceSession.create(`${MODEL_PATH}${this.definition.file}`, opts),
+ ]);
+ this._mel = mel;
+ this._embed = embed;
+ this._model = model;
+ }
+
+ /**
+ * Swap the listening phrase without tearing down the audio graph. The mel and
+ * embedding stages are shared across every wake word, so only the small
+ * classifier is refetched.
+ */
+ async setWakeWord(id) {
+ const next = wakeWordById(id);
+ if (next.id === this.definition.id) return;
+ this.definition = next;
+ if (!this._ort) return;
+ this._model = await this._ort.InferenceSession.create(`${MODEL_PATH}${next.file}`, {
+ executionProviders: ['wasm'],
+ });
+ this.reset();
+ }
+
+ /**
+ * Feed one frame of 16 kHz mono audio in [-1, 1]. Frames of any length are
+ * accepted; scoring happens on 80 ms boundaries. Returns immediately, and
+ * inference runs off the caller's stack.
+ *
+ * @param {Float32Array} frame
+ */
+ push(frame) {
+ if (!this._model || !frame?.length) return;
+ this._lastFrameAt = now();
+ let offset = 0;
+ while (offset < frame.length) {
+ const room = CHUNK_SAMPLES - this._pendingLength;
+ const take = Math.min(room, frame.length - offset);
+ this._pending.set(frame.subarray(offset, offset + take), this._pendingLength);
+ this._pendingLength += take;
+ offset += take;
+ if (this._pendingLength === CHUNK_SAMPLES) {
+ const chunk = this._pending.slice(0);
+ this._pendingLength = 0;
+ void this._consume(chunk);
+ }
+ }
+ }
+
+ /**
+ * Clear every buffer. Called when the mic is muted, when the agent stops
+ * speaking, and on a wake, so that no audio from before the boundary can
+ * contribute to a score after it.
+ */
+ reset() {
+ this._rawFilled = 0;
+ this._raw.fill(0);
+ this._pendingLength = 0;
+ this._melRing.reset();
+ this._featureRing.reset();
+ this._above = false;
+ this.lastScore = 0;
+ this.suppressedPeak = 0;
+ }
+
+ /** Release the sessions. Idempotent. */
+ async destroy() {
+ const sessions = [this._mel, this._embed, this._model];
+ this._mel = this._embed = this._model = null;
+ this._loading = null;
+ for (const s of sessions) {
+ try {
+ await s?.release?.();
+ } catch {}
+ }
+ }
+
+ // One 80 ms chunk: mel -> embedding -> score.
+ async _consume(chunk) {
+ // A dropped chunk is better than a queue: on a machine slow enough to fall
+ // behind, an unbounded backlog turns a 200 ms detection into a 3 s one.
+ if (this._inflight) return;
+ this._inflight = true;
+ const chunkAt = this._lastFrameAt;
+ try {
+ this._appendRaw(chunk);
+ if (this._rawFilled < this._raw.length) return;
+
+ const melFrames = await this._melspectrogram(this._raw);
+ for (let i = 0; i < melFrames.length; i += MEL_BINS) {
+ this._melRing.push(melFrames.subarray(i, i + MEL_BINS));
+ }
+ if (!this._melRing.full) return;
+
+ const embedding = await this._embedding(this._melRing.snapshot());
+ this._featureRing.push(embedding);
+ if (!this._featureRing.full) return;
+
+ const score = await this._score(this._featureRing.snapshot());
+ this.lastScore = score;
+ this.onScore(score);
+
+ if (this.suppressed) {
+ this.suppressedPeak = Math.max(this.suppressedPeak, score);
+ this._above = score >= this.threshold;
+ return;
+ }
+
+ const crossed = score >= this.threshold && !this._above;
+ this._above = score >= this.threshold;
+ if (!crossed) return;
+ const t = now();
+ if (t - this._lastWakeAt < REFRACTORY_MS) return;
+ this._lastWakeAt = t;
+ // Measured from the frame that completed the chunk, so the number
+ // covers exactly what this module is responsible for: the inference,
+ // not the audio that had not arrived yet.
+ const latencyMs = t - chunkAt;
+ this.reset();
+ this._lastWakeAt = t;
+ this.onWake({ score, latencyMs, wakeWord: this.definition.id });
+ } catch (err) {
+ log.warn('[wake-word]', err?.message);
+ } finally {
+ this._inflight = false;
+ }
+ }
+
+ // Keep the last 1760 samples: 1280 new plus the model's 480-sample lookback.
+ _appendRaw(chunk) {
+ this._raw.copyWithin(0, chunk.length);
+ this._raw.set(chunk, this._raw.length - chunk.length);
+ this._rawFilled = Math.min(this._raw.length, this._rawFilled + chunk.length);
+ }
+
+ async _melspectrogram(samples) {
+ const scaled = new Float32Array(samples.length);
+ for (let i = 0; i < samples.length; i++) scaled[i] = samples[i] * INT16_SCALE;
+ const input = new this._ort.Tensor('float32', scaled, [1, scaled.length]);
+ const out = await this._mel.run({ [this._mel.inputNames[0]]: input });
+ const raw = out[this._mel.outputNames[0]].data;
+ // Upstream's transform. It is not a normalisation choice of ours: the
+ // embedding model was trained on exactly this, so it is part of the graph.
+ const mel = new Float32Array(raw.length);
+ for (let i = 0; i < raw.length; i++) mel[i] = raw[i] / 10 + 2;
+ return mel;
+ }
+
+ async _embedding(melWindow) {
+ const input = new this._ort.Tensor('float32', melWindow, [1, EMBEDDING_WINDOW_FRAMES, MEL_BINS, 1]);
+ const out = await this._embed.run({ [this._embed.inputNames[0]]: input });
+ return out[this._embed.outputNames[0]].data;
+ }
+
+ async _score(features) {
+ const input = new this._ort.Tensor('float32', features, [1, PREDICTION_EMBEDDINGS, EMBEDDING_DIMS]);
+ const out = await this._model.run({ [this._model.inputNames[0]]: input });
+ return out[this._model.outputNames[0]].data[0];
+ }
+}
+
+/**
+ * Seconds of audio the detector must see before it can produce its first score:
+ * the 760 ms mel window plus 16 embeddings at 80 ms each. Surfaced so the UI can
+ * tell the truth about when listening actually begins instead of claiming to
+ * listen while the buffers are still filling.
+ */
+export const WARMUP_MS =
+ (EMBEDDING_WINDOW_FRAMES * MEL_HOP_SAMPLES + PREDICTION_EMBEDDINGS * CHUNK_SAMPLES) / 16;