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
feat(home): ship the relay service, the MCP surface and the privacy window
nirholase71b1fe1f3d5
diff --git a/.gitignore b/.gitignoreindex 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 anddiff --git a/api/_lib/home/privacy.js b/api/_lib/home/privacy.jsnew file mode 100644index 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}`,+ ? 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.jsindex 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/LICENSEnew file mode 100644index 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.jsnew file mode 100644index 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.mjsindex 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/Dockerfilenew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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;