hci-atrium 0.3.0 → 0.4.0

package/dist/rooms/owned-room.js

@@ -0,0 +1,844 @@
+/**
+ * The **owned** room handle — {@link ./room.Room} plus every surface that needs the account
+ * credential behind it. Returned by ``client.rooms.open`` / ``.get`` / ``.list``, which inject the
+ * authenticated REST caller and the client slice this class is built on.
+ *
+ * The split is deliberate: a loginless ``joinRoom(code)`` handle is a plain {@link ./room.Room}, so
+ * the members here are not merely guarded at runtime — they are absent from its type. Everything on
+ * this class assumes a credential and calls it directly ({@link OwnedRoomDeps} makes ``rest`` /
+ * ``client`` required), so nothing here needs a runtime credential guard.
+ *
+ * Durable & reactive: {@link OwnedRoom.record} bridges the room into a session over an SSE-observe
+ * {@link ./recorder.Recorder} (a room stores nothing itself, so durable capture rides the observe
+ * stream); {@link OwnedRoom.audioVectors} embeds the live snippet stream and
+ * {@link OwnedRoom.audioScores} fuses it against named anchors for a {@link ../decider.Decider};
+ * the standing offers and capability brokers serve code-joined peers on your credential.
+ */
+import { by, toAnchorMembers } from "../by.js";
+import { Dashboard } from "../dash.js";
+import { APIError, AtriumError } from "../errors.js";
+import { asError } from "../http.js";
+import { buildRoomRotateCode, buildRoomSignal } from "../shaping/rooms.js";
+import { RoomTrace, traceEnvelope, traceStateType } from "../trace.js";
+import { BrokerError, CAPTURE_OFFER_ROLE, CHAT_BROKER_ROLE, DEFAULT_CHAT_MAX_TOKENS, DEFAULT_MAX_ANCHORS, EMBED_BROKER_ROLE, parseAnchorDescriptor, TRANSCRIPTION_OFFER_ROLE, validateChatMessages, } from "./brokers.js";
+import { OfferedCapture } from "./offer-capture.js";
+import { OfferedTranscription } from "./offer-transcription.js";
+import { Recorder } from "./recorder.js";
+import { RAW_CONSUMER_QUEUE_MAX, Room, randomId, remove, } from "./room.js";
+import { AUDIO_SNIPPET_CONSUMER_ROLE, decodeAudioSnippetFrame, } from "./snippet.js";
+import { TRANSCRIBER_SOURCE, Transcriber } from "./transcriber.js";
+import { RoomSocket } from "./transport.js";
+export class OwnedRoom extends Room {
+    // The change-listeners a capture offer subscribes with — the recorder-registration seam
+    // (`_notify_recorders_changed` in Python). Cleared by `teardown`; an offer also unsubscribes
+    // itself when the room winds it down.
+    recorderListeners = new Set();
+    // The constructor exists to narrow the parameter: the inherited one would accept a bare RoomDeps,
+    // whose missing `rest`/`client` every member here assumes.
+    // biome-ignore lint/complexity/noUselessConstructor: it narrows the constructor's parameter type.
+    constructor(deps) {
+        super(deps);
+    }
+    // ── Durable capture (record → session) ───────────────────────────────────
+    /**
+     * Start capturing this room's live signals into a durable ``session`` — the single durable binding
+     * between a room (pure transport) and a session (an append-only log). A **side effect**: it starts
+     * immediately in the background and returns a live {@link Recorder} handle. Stop it with
+     * ``rec.stop()``, or let {@link close} (an ``await using`` room) stop it. It skips ``ephemeral``
+     * signals and presence traffic — only durable-worthy signals are recorded, each stamped with
+     * ``via`` provenance (``{ room_id, room_name, from, to }``). Mirror of Python's ``room.record``.
+     *
+     * A dropped stream reconnects with backoff (the gap is lost — rooms have no replay); only a
+     * terminal end stops it cleanly with a {@link Recorder.stoppedReason} (a code rotation, or the
+     * room being gone / its code rejected — the latter also sets {@link Recorder.error}).
+     */
+    record(into) {
+        const rest = this.deps.rest;
+        // The `trace.state.recorder` line rides the same change seam, on TRANSITIONS only (the seam also
+        // fires on a no-op stop) — mirror of Python's start/stop emissions in the recorder's own task.
+        let tracedAlive = false;
+        const recorder = new Recorder({
+            roomId: this.id,
+            code: this.connectCode,
+            roomName: this.name,
+            baseUrl: this.deps.baseUrl,
+            rest,
+            reconnect: this.deps.reconnect,
+            fetchImpl: this.deps.fetchImpl,
+            onChange: () => {
+                void this.notifyRecordersChanged();
+                if (recorder.alive === tracedAlive)
+                    return;
+                tracedAlive = recorder.alive;
+                void this.traceState("recorder", tracedAlive
+                    ? `recording ${into.id}: started`
+                    : `recording ${into.id}: stopped (${recorder.events} events)`);
+            },
+        }, into);
+        this.recorders.push(recorder);
+        recorder.start();
+        return recorder;
+    }
+    /** The recorders currently running on this handle (membership **and** liveness — a stopped one no
+     * longer counts) — the source of truth a wave-4 ``offerAudioCapture`` reads for audio-capture
+     * availability, and binds its capture to the first active recorder's session. */
+    activeRecorders() {
+        return this.recorders.filter((r) => r.alive);
+    }
+    /** Register a listener fired whenever the active-recorder set changes (a {@link record} started, or
+     * a recorder stopped/terminated) — the seam a wave-4 ``offerAudioCapture`` binds to, so it can
+     * re-derive availability and disengage when the recorder it wrote under is gone. Returns an
+     * unsubscribe function. Mirror of Python's ``_notify_recorders_changed`` registration. */
+    onRecordersChanged(listener) {
+        this.recorderListeners.add(listener);
+        return () => {
+            this.recorderListeners.delete(listener);
+        };
+    }
+    async notifyRecordersChanged() {
+        // Isolate each hook — one misbehaving listener must not starve the others nor throw out of a
+        // recorder's teardown path (this fires from a recorder's terminal wind-down).
+        for (const listener of [...this.recorderListeners]) {
+            try {
+                await listener();
+            }
+            catch (err) {
+                console.error("Atrium room: a recorders-changed listener failed:", err);
+            }
+        }
+    }
+    // ── Live transcription (the transcript.* broker) ─────────────────────────
+    /**
+     * Transcribe this room's live audio into ``transcript.*`` signals — the in-room broker. Consumes the
+     * room's ``audio.snippet`` stream (announcing the snippet-consumer role, so a Player starts
+     * capturing), pushes it through the same engine as {@link ../atrium.Atrium.transcribeLive} on
+     * **your** credentials/compute, and publishes back:
+     *
+     * * ``transcript.partial`` — ``{ text }``, **ephemeral** (a live caption the recorder skips).
+     *   Wholesale-replaced — render the latest, don't append.
+     * * ``transcript.final`` — ``{ text, start, end, seq }``, durable (the {@link record} bridge persists
+     *   it — no new recording API). ``seq`` is a per-handle counter from 0; the signal's ``source`` is
+     *   ``"transcriber"``.
+     *
+     * Any consumer — including a loginless code-joined tool — just does ``room.on("transcript.final")``.
+     * Like {@link record}, it's a **side effect**: it starts immediately in the background and is stopped
+     * when the room closes, or via ``await handle.stop()`` / ``await using``.
+     */
+    transcribe(opts = {}) {
+        const client = this.deps.client;
+        const transcriber = new Transcriber({
+            model: opts.model,
+            language: opts.language,
+            snippetBytes: (signal) => this.snippetBytesFor(signal),
+            engine: (clips, o) => client.transcribeStream(clips, {
+                model: o.model,
+                language: o.language,
+                // The producer ships Opus-in-WebM; the backend decodes each clip. Partials are published
+                // as ephemeral live captions, so the engine must surface them.
+                format: "webm",
+                partials: true,
+                skipEmpty: true,
+                signal: o.signal,
+                webSocketCtor: this.deps.webSocketCtor,
+            }),
+            publish: (type, payload, o) => client.request(buildRoomSignal(this.id, {
+                type,
+                payload,
+                source: TRANSCRIBER_SOURCE,
+                ephemeral: o.ephemeral,
+            })),
+            onEnd: (err) => void this.traceState("transcriber", err ? `transcribing: failed — ${err.message}` : "transcribing: stopped"),
+        });
+        this.transcribers.push(transcriber);
+        transcriber.start();
+        void this.traceState("transcriber", `transcribing (${opts.model ?? "default"}): started`);
+        return transcriber;
+    }
+    /**
+     * Subscribe to the room's live ``audio.snippet`` stream and transcribe it, yielding a
+     * {@link ../models.Transcript} per finalized sentence — the speech-to-text sibling of
+     * {@link audioVectors}, and the *raw* counterpart of the {@link transcribe} broker (which publishes
+     * ``transcript.*`` signals for every peer instead of handing you the stream).
+     *
+     * Subscribing *is* the demand signal (it announces the ``audio-snippet-consumer`` role, so a
+     * producer's own default-off "Share audio clips" toggle actually captures). Break out of the
+     * ``for await`` loop — or abort ``signal`` — to end the subscription and close the socket.
+     *
+     * Snippets run through the same engine as {@link ../atrium.Atrium.transcribeLive}: true streaming
+     * (per-sentence finals, plus revisable partials with ``partials``) when the backend's live route is
+     * reachable, degrading silently to per-clip batch transcription otherwise (finals only).
+     * Transcription runs on *your* credentials/compute — a rejected credential raises rather than
+     * falling back.
+     *
+     * The two paths differ in one detail (mirror of Python's ``audio_transcripts``): on the **fallback**
+     * path each transcript carries its source frame's ``sequence`` / ``window_seconds`` under
+     * ``transcript.raw.snippet`` (a cheap ordering/correlation handle) and the clip's format comes from
+     * that frame's own MIME type; on the **streaming** path transcripts are per-sentence, so there is no
+     * 1:1 snippet correlation and ``raw.snippet`` is omitted (``raw`` carries ``start`` / ``end``).
+     */
+    async *audioTranscripts(opts = {}) {
+        const client = this.deps.client;
+        const skipEmpty = opts.skipEmpty ?? true;
+        // Own abort, chained to the caller's: a consumer that just `break`s out of the loop must tear the
+        // whole chain down, and JS can't cancel the engine's pending feeder `await` the way Python cancels
+        // its task — aborting closes the snippet socket, which is what unblocks it (same teardown seam as
+        // the `transcribe()` handle's stop()).
+        const ctrl = new AbortController();
+        const chain = () => ctrl.abort();
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                ctrl.abort();
+            else
+                opts.signal.addEventListener("abort", chain, { once: true });
+        }
+        // One shared snippet source: the streaming path draws its bytes, the fallback its frames + their
+        // per-frame metadata. Only one of the two ever iterates it (the engine picks a path).
+        const frames = this.snippetStream(`audio-transcripts:${randomId().slice(0, 8)}`, ctrl.signal);
+        async function* snippetBytes() {
+            for await (const frame of frames)
+                yield frame.data;
+        }
+        async function* snippetFallback() {
+            for await (const frame of frames) {
+                const format = frame.mimeType.split(";")[0]?.split("/").pop();
+                let said;
+                try {
+                    said = await client.transcribe(new Blob([frame.data], { type: frame.mimeType }), {
+                        model: opts.model,
+                        language: opts.language,
+                        format,
+                    });
+                }
+                catch (err) {
+                    if (err instanceof APIError && (err.status === 401 || err.status === 403))
+                        throw err;
+                    continue; // a frame the server couldn't transcribe — skip, keep the stream alive
+                }
+                if (!said.text && skipEmpty)
+                    continue;
+                said.raw.snippet = { sequence: frame.sequence, window_seconds: frame.windowSeconds };
+                yield said;
+            }
+        }
+        const stream = client.transcribeStream(snippetBytes(), {
+            model: opts.model,
+            language: opts.language,
+            format: "webm", // the producer ships Opus-in-WebM; the backend decodes each clip
+            partials: opts.partials ?? false,
+            skipEmpty,
+            signal: ctrl.signal,
+            webSocketCtor: this.deps.webSocketCtor,
+            fallback: snippetFallback,
+        });
+        const engine = stream[Symbol.asyncIterator]();
+        // Pulled by hand (not `yield*`) so teardown runs in the order that actually unwinds: abort the
+        // socket FIRST, then wind the engine down — `yield*` would forward the consumer's `return()`
+        // into the engine while its feeder is still parked on a snippet that will never arrive.
+        try {
+            for (;;) {
+                const next = await engine.next();
+                if (next.done)
+                    break;
+                yield next.value;
+            }
+        }
+        finally {
+            opts.signal?.removeEventListener("abort", chain);
+            ctrl.abort();
+            await engine.return?.().catch(() => { });
+        }
+    }
+    // The raw snippet bytes for the transcription broker — a dedicated consumer socket, ended when the
+    // handle's stop() aborts the signal (which closes the socket).
+    async *snippetBytesFor(signal) {
+        for await (const frame of this.snippetStream(`transcriber:${randomId().slice(0, 8)}`, signal)) {
+            yield frame.data;
+        }
+    }
+    requirePreConnect() {
+        if (this.connectionId !== null) {
+            throw new AtriumError("register offer_*/offerEmbeds/offerChat before connect() — the broker role is only " +
+                "advertised when the connection opens");
+        }
+    }
+    offerDeps(client) {
+        return {
+            roomId: this.id,
+            getCode: () => this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            reconnect: this.deps.reconnect,
+            webSocketCtor: this.deps.webSocketCtor,
+            // The offer consults the room's latched transport decision — refuse fast on an SSE handle.
+            requireWsAudio: () => this.requireWsAudio("this standing offer"),
+            // The ``*.available`` broadcast (and per-source ``transcript.*``) ride the REST /signal POST so
+            // an ephemeral hint survives — the WS inbound path forces ``ephemeral: false``.
+            publishSignal: (type, payload, o) => client.request(buildRoomSignal(this.id, { type, payload, source: o.source, ephemeral: o.ephemeral })),
+            // The armed/active transition an offer broadcasts also surfaces to any room tracer (deduped
+            // with the broadcast itself) — Python's `_trace_state` call in `_StandingSource._broadcast`.
+            traceState: (label, summary, detail) => this.traceState(label, summary, detail),
+        };
+    }
+    // Wire a peer-toggleable standing service (the third broker kind) — announce ``role`` and route the
+    // ``<name>.start`` / ``.stop`` / ``.status`` requests to ``service`` (mirror of ``_offer_service``).
+    // Engage is sender-scoped (the server-stamped ``from``) unless the payload carries ``all: true``.
+    offerService(name, role, service) {
+        this.requirePreConnect();
+        this.announceRole(role);
+        this.offeredServices.push(service);
+        this.on(`${name}.start`, async (e) => {
+            try {
+                await service.start({ source: e.from, all: Boolean(e.payload.all) });
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            return { ok: true };
+        });
+        this.on(`${name}.stop`, async (e) => {
+            try {
+                await service.stopRequest({ source: e.from, all: Boolean(e.payload.all) });
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            return { ok: true };
+        });
+        this.on(`${name}.status`, () => ({ ok: true, ...service.status() }));
+    }
+    /**
+     * Offer live transcription as a peer-toggleable standing service — a code-joined tool turns it on
+     * with a ``transcription.start`` request and off with ``transcription.stop`` (both idempotent).
+     * Announces the discoverable ``transcription-offer`` role. **Scoped, multi-source**: ``start`` /
+     * ``stop`` are scoped to the requesting connection unless the payload carries ``{ all: true }``;
+     * only armed sources are transcribed (up to ``maxSources``, default 8). While on it runs the same
+     * engine as {@link transcribe} on **your** credentials, publishing source-attributed ``transcript.*``
+     * signals. Register **before** ``connect()``.
+     * Returns the handle (for ``handle.start({ all: true })`` from the host). Mirror of Python's
+     * ``offer_transcription``.
+     */
+    offerTranscription(opts = {}) {
+        const client = this.deps.client;
+        const service = new OfferedTranscription({
+            ...this.offerDeps(client),
+            engine: (clips, o) => client.transcribeStream(clips, {
+                model: o.model,
+                language: o.language,
+                format: "webm", // the producer ships Opus-in-WebM; the backend decodes each clip
+                partials: true,
+                skipEmpty: true,
+                signal: o.signal,
+                webSocketCtor: this.deps.webSocketCtor,
+            }),
+        }, { model: opts.model, language: opts.language, maxSources: opts.maxSources });
+        this.offerService("transcription", TRANSCRIPTION_OFFER_ROLE, service);
+        return service;
+    }
+    /**
+     * Offer audio capture as a peer-toggleable standing service — **session-less**: it writes into the
+     * **active recorder's** session ({@link record} is the single durable binding), so a ``capture.start``
+     * with no active recorder replies an error. A code-joined tool toggles it via ``capture.start`` /
+     * ``capture.stop`` (idempotent). Announces the discoverable ``capture-offer`` role. **Scoped,
+     * multi-source** (up to ``maxSources``, default 8): only armed sources are recorded; a same-name
+     * reconnect within grace resumes one file, two simultaneous same-name producers get their own files.
+     * Register **before** ``connect()``. Returns the
+     * handle (for ``handle.start({ all: true })``). Mirror of Python's ``offer_audio_capture``.
+     */
+    offerAudioCapture(opts = {}) {
+        const client = this.deps.client;
+        const service = new OfferedCapture({
+            ...this.offerDeps(client),
+            request: (req) => client.request(req),
+            activeRecorders: () => this.activeRecorders(),
+            onRecordersChanged: (listener) => this.onRecordersChanged(listener),
+        }, { maxSources: opts.maxSources });
+        this.offerService("capture", CAPTURE_OFFER_ROLE, service);
+        return service;
+    }
+    async resolveEmbedSpace(client, requested) {
+        const spaces = await client.library.spaces();
+        if (requested !== undefined) {
+            const matched = spaces.find((s) => s.id === requested);
+            return { space: requested, model: matched?.model ?? null };
+        }
+        const matched = spaces.find((s) => s.defaultModalities.includes("text"));
+        if (!matched) {
+            throw new AtriumError("no default text search space is configured on this deployment — the embed.resolve request " +
+                "must pass space");
+        }
+        return { space: matched.id, model: matched.model ?? null };
+    }
+    async resolveAnchorVector(client, desc, space, model, cache) {
+        const anchor = parseAnchorDescriptor(desc); // throws BrokerError on a malformed anchor
+        if (anchor.kind === "vector")
+            return [...anchor.vector];
+        if (anchor.kind === "asset") {
+            const key = `${space}|asset:${anchor.asset}:${anchor.matchBy ?? ""}`;
+            let vec = cache.get(key);
+            if (!vec) {
+                const query = { space };
+                if (anchor.matchBy !== null)
+                    query.match_by = anchor.matchBy;
+                const rows = (await client.request({
+                    method: "GET",
+                    path: `/v1/assets/${anchor.asset}/vectors`,
+                    query,
+                }));
+                const first = Array.isArray(rows) ? rows[0] : undefined;
+                if (!first || !Array.isArray(first.vector)) {
+                    throw new BrokerError(`asset '${anchor.asset}' has no stored vector in space '${space}'`);
+                }
+                vec = first.vector.map(Number);
+                cache.set(key, vec);
+            }
+            return vec;
+        }
+        if (anchor.kind === "text") {
+            const key = `${space}|text:${anchor.text}`;
+            let vec = cache.get(key);
+            if (!vec) {
+                if (model === null) {
+                    throw new BrokerError(`space '${space}' has no model configured — cannot embed text`);
+                }
+                vec = await client.embed({ text: anchor.text, model });
+                cache.set(key, vec);
+            }
+            return vec;
+        }
+        const key = `${space}|concept:${anchor.concept}:${anchor.collection ?? ""}`;
+        let vec = cache.get(key);
+        if (!vec) {
+            const query = { concept: anchor.concept, space };
+            if (anchor.collection !== null)
+                query.collection = anchor.collection;
+            const data = (await client.request({
+                method: "GET",
+                path: "/v1/library/concept-vector",
+                query,
+            }));
+            vec = data.vector.map(Number);
+            cache.set(key, vec);
+        }
+        return vec;
+    }
+    /**
+     * Handle ``embed.resolve`` requests from code-joined peers (e.g. a loginless Unity scene) — resolve
+     * named operand descriptors (``{ text }`` / ``{ concept, collection? }`` / ``{ vector }`` /
+     * ``{ asset, match_by? }``) to vectors in ONE embedding space, so a peer with no credentials can
+     * compare live signals against library concepts/text/assets. **The requester chooses the space**
+     * (omitted → the default text space). A per-anchor
+     * failure lands in ``errors`` without failing the others; a malformed / over-``maxAnchors`` request
+     * or a ``space`` outside ``spaces`` gets a whole-request ``{ error }``. Announces the discoverable
+     * ``embed-broker`` role — call before ``connect()``. Mirror of Python's ``offer_embeds``.
+     */
+    offerEmbeds(opts = {}) {
+        const client = this.deps.client;
+        this.requirePreConnect();
+        const allowed = opts.spaces ? new Set(opts.spaces) : null;
+        const maxAnchors = opts.maxAnchors ?? DEFAULT_MAX_ANCHORS;
+        const cache = new Map();
+        this.announceRole(EMBED_BROKER_ROLE);
+        this.on("embed.resolve", async (e) => {
+            const anchors = e.payload.anchors;
+            if (typeof anchors !== "object" ||
+                anchors === null ||
+                Array.isArray(anchors) ||
+                Object.keys(anchors).length === 0) {
+                return { error: "anchors must be a non-empty object" };
+            }
+            const entries = Object.entries(anchors);
+            if (entries.length > maxAnchors) {
+                return { error: `too many anchors (${entries.length} > ${maxAnchors})` };
+            }
+            const requested = typeof e.payload.space === "string" ? e.payload.space : undefined;
+            if (requested !== undefined && allowed !== null && !allowed.has(requested)) {
+                return { error: `space '${requested}' is not served by this broker` };
+            }
+            let space;
+            let model;
+            try {
+                ;
+                ({ space, model } = await this.resolveEmbedSpace(client, requested));
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            if (allowed !== null && !allowed.has(space)) {
+                return { error: `space '${space}' is not served by this broker` };
+            }
+            const vectors = {};
+            const errors = {};
+            for (const [nm, desc] of entries) {
+                try {
+                    vectors[nm] = await this.resolveAnchorVector(client, desc, space, model, cache);
+                }
+                catch (err) {
+                    errors[nm] = asError(err).message;
+                }
+            }
+            const reply = { space, vectors };
+            if (Object.keys(errors).length > 0)
+                reply.errors = errors;
+            return reply;
+        });
+    }
+    /**
+     * Handle ``chat.generate`` requests from code-joined peers — a stateless chat completion (no history
+     * broker-side), so a loginless peer gets an LLM reply without its own credentials. Reply:
+     * ``{ text, model }``, or ``{ error }`` if ``messages`` is malformed / over the payload cap. The
+     * **broker** pins ``model`` (the requester cannot choose it — cost control); ``maxTokens`` caps each
+     * reply. Announces the discoverable ``chat-broker`` role — call before ``connect()``. Every peer
+     * holding the connect code can trigger a reply on **your** billing. Mirror of Python's ``offer_chat``.
+     */
+    offerChat(opts = {}) {
+        const client = this.deps.client;
+        this.requirePreConnect();
+        const maxTokens = opts.maxTokens ?? DEFAULT_CHAT_MAX_TOKENS;
+        this.announceRole(CHAT_BROKER_ROLE);
+        this.on("chat.generate", async (e) => {
+            let messages;
+            try {
+                messages = validateChatMessages(e.payload.messages);
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            try {
+                const reply = await client.chat(messages, {
+                    model: opts.model,
+                    params: { max_tokens: maxTokens },
+                });
+                return { text: reply.content, model: reply.model };
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+        });
+    }
+    // ── Observation dashboard + tracing (host-side helpers) ──────────────────
+    /**
+     * Build the host-side {@link ../dash.Dashboard} for this room — the live observation-dashboard
+     * state an app holds as a grid of tiles. It answers each joining ``/tools/dashboard`` with a full
+     * ``dash.snapshot`` and broadcasts ``dash.delta`` patches as things change, all **ephemeral** (the
+     * room stores nothing — the durable record is the session).
+     *
+     * Prefer this over ``new Dashboard(room)``: it publishes over the REST ``/signal`` POST, which
+     * preserves the dialect's ephemerality (the WS inbound path forces ``ephemeral: false``). Mirror of
+     * Python's ``Dashboard(room)``.
+     */
+    dashboard(opts = {}) {
+        const client = this.deps.client;
+        return new Dashboard(this, {
+            ...opts,
+            publish: (type, payload, o) => client.request(buildRoomSignal(this.id, {
+                type,
+                payload,
+                to: o.to,
+                ephemeral: o.ephemeral,
+                connectionId: this.connectionId,
+            })),
+        });
+    }
+    /**
+     * Mirror the SDK's own activity into this room as ``trace.*`` signals — one line turns it on. The
+     * operation folds into the signal type (``label`` still rides the payload), and ephemerality is
+     * per-signal (see {@link ../trace.isTraceEphemeral}). While tracing:
+     *
+     * * **library/model calls** made through the same client (``search`` / ``searchByExamples`` /
+     *   ``enrich`` / ``play`` / ``chat``) surface a ``trace.<label>`` (``trace.library.search`` /
+     *   ``trace.chat`` / ``trace.play``) — a glanceable summary (``"rain" → 8 hits (top: Forest Rain
+     *   0.83)``) plus a capped detail (top-N results, never full payloads);
+     * * **SDK-internal state** — a recorder start/stop (with its session + event count), a transcriber
+     *   start/stop, a standing offer's armed/active roster — surfaces a ``trace.state.<label>``.
+     *
+     * Default OFF (it broadcasts app internals to anyone with the code, and it's noise on the happy
+     * path). Returns a handle: ``const t = room.trace()`` then ``t.stop()``, or ``using t =
+     * room.trace()`` for a scope; stopped when the room closes. A trace failure never breaks the traced
+     * call. ``play`` and the state seam are scoped to **this** room; client-wide calls mirror into every
+     * armed room. Mirror of Python's ``room.trace()``.
+     */
+    trace() {
+        const client = this.deps.client;
+        const handle = new RoomTrace({
+            // Trace signals ride the REST /signal POST, like the transcriber's: the WS inbound path forces
+            // `ephemeral: false`, and trace ephemerality is per-signal (a durable `trace.library.search` IS
+            // the study's record; an ephemeral `trace.play` must not double-record the play).
+            publish: (type, payload, o) => client.request(buildRoomSignal(this.id, {
+                type,
+                payload,
+                ephemeral: o.ephemeral,
+                connectionId: this.connectionId,
+            })),
+            onStop: () => {
+                remove(client.traceSinks, handle);
+                remove(this.traceHandles, handle);
+            },
+        });
+        client.traceSinks?.push(handle);
+        this.traceHandles.push(handle);
+        return handle;
+    }
+    // Emit a `trace.state.<label>` into every tracing session on this room (no-op when none — the
+    // zero-cost-when-off contract). Mirror of Python's `_trace_state`.
+    async traceState(label, summary, detail) {
+        if (this.traceHandles.length === 0)
+            return;
+        const payload = traceEnvelope(label, summary, detail);
+        for (const handle of [...this.traceHandles])
+            await handle.emit(traceStateType(label), payload);
+    }
+    // ── Audio embedding (vectors + reactive scores) ──────────────────────────
+    // Resolve the (space, model) pair for the audio surfaces (mirror of Python's `_resolve_audio_space`):
+    // an explicit space+model skips the lookup; otherwise the member-facing spaces list resolves the
+    // deployment's default audio space and/or reads the space's configured model.
+    async resolveAudioSpace(space, model) {
+        if (space !== undefined && model !== undefined)
+            return { space, model };
+        const spaces = await this.deps.client.library.spaces();
+        let matched;
+        if (space === undefined) {
+            matched = spaces.find((s) => s.defaultModalities.includes("audio"));
+            if (!matched) {
+                throw new Error("no default audio search space is configured on this deployment — pass space to audioVectors()");
+            }
+            space = matched.id;
+        }
+        else {
+            matched = spaces.find((s) => s.id === space);
+            if (!matched)
+                throw new Error(`space '${space}' not found`);
+        }
+        return { space, model: model ?? matched?.model ?? null };
+    }
+    // A dedicated snippet-consumer socket (announcing the demand role so a producer captures), decoding
+    // its binary frames — the shared source behind audioVectors/audioScores (mirror of audioClips).
+    async *snippetStream(identity, signal) {
+        this.requireWsAudio("live audio streaming");
+        const queue = [];
+        let wake = null;
+        let ended = false;
+        const socket = new RoomSocket({
+            roomId: this.id,
+            code: this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            identity,
+            announce: { ...this.deps.announce, role: AUDIO_SNIPPET_CONSUMER_ROLE },
+            reconnect: this.deps.reconnect,
+            webSocketCtor: this.deps.webSocketCtor,
+            onBinary: (data) => {
+                const frame = decodeAudioSnippetFrame(data);
+                if (!frame)
+                    return; // a foreign / DSP binary frame — not ours
+                if (queue.length >= RAW_CONSUMER_QUEUE_MAX)
+                    queue.shift(); // drop oldest — bound a slow consumer
+                queue.push(frame);
+                wake?.();
+                wake = null;
+            },
+            onEnd: () => {
+                ended = true;
+                wake?.();
+                wake = null;
+            },
+        });
+        // An abort (a `transcribe()` handle's stop) closes the socket → ends this generator at once.
+        const onAbort = () => {
+            ended = true;
+            socket.close();
+            wake?.();
+            wake = null;
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort);
+        }
+        try {
+            try {
+                await socket.connect();
+            }
+            catch (err) {
+                // A pre-/mid-connect abort closed the socket → connect() rejects "room closed"; that's an
+                // expected teardown, not a failure. Only a genuine connect error (bad code) propagates.
+                if (!ended)
+                    throw err;
+            }
+            while (!ended) {
+                while (queue.length > 0)
+                    yield queue.shift();
+                if (ended)
+                    break;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+            while (queue.length > 0)
+                yield queue.shift();
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+            socket.close();
+        }
+    }
+    /**
+     * Subscribe to the room's live ``audio.snippet`` stream and embed each ~10s window, yielding an
+     * {@link AudioVector} per snippet — a live vector of "what the room sounds like right now".
+     * Subscribing *is* the demand signal (announces the ``audio-snippet-consumer`` role, so a
+     * producer's default-off "Share audio clips" toggle actually captures). Break out of the
+     * ``for await`` loop to end it. Mirror of Python's ``audio_vectors``.
+     *
+     * ``space`` pins the search space snippets are labeled with (default: the deployment's default
+     * audio space, so a no-arg vector is comparable against library-derived vectors); ``model`` the
+     * embedding model (default: the resolved space's configured model). ``relay: true`` also relays
+     * each vector into the room as an ephemeral ``audio.vector`` signal — so a loginless code-joined
+     * peer can consume the live mood vector without credentials of its own. Binary rides the
+     * WebSocket only.
+     */
+    async *audioVectors(opts = {}) {
+        const client = this.deps.client;
+        const { space, model } = await this.resolveAudioSpace(opts.space, opts.model);
+        if (model === null) {
+            throw new Error(`the audio search space '${space}' has no model configured — pass model to audioVectors()`);
+        }
+        for await (const frame of this.snippetStream(`audio-vectors:${randomId().slice(0, 8)}`)) {
+            const fmt = frame.mimeType.split(";")[0]?.split("/").pop();
+            const vector = await client.embed({
+                audio: new Blob([frame.data], { type: frame.mimeType }),
+                model,
+                format: fmt,
+            });
+            const vec = {
+                vector,
+                space,
+                sequence: frame.sequence,
+                windowSeconds: frame.windowSeconds,
+                timestamp: Date.now() / 1000,
+            };
+            if (opts.relay) {
+                // Over the REST /signal POST, like the dashboard's and the transcriber's publishes: the WS
+                // inbound path forces ``ephemeral: false``, and a durable relay would write one full vector
+                // per ~10s window into every recording session.
+                await client.request(buildRoomSignal(this.id, {
+                    type: "audio.vector",
+                    payload: {
+                        vector: vec.vector,
+                        space: vec.space,
+                        sequence: vec.sequence,
+                        window_seconds: vec.windowSeconds,
+                        timestamp: vec.timestamp,
+                    },
+                    ephemeral: true,
+                    connectionId: this.connectionId,
+                }));
+            }
+            yield vec;
+        }
+    }
+    async preflightConceptAnchors(members, space) {
+        // Resolve every concept anchor's vector once before waiting on any frame — a typo'd/unresolvable
+        // concept fails immediately, naming the anchor, rather than surfacing mid-stream.
+        const client = this.deps.client;
+        for (const [name, ops] of Object.entries(members)) {
+            for (const op of ops) {
+                if (op.kind !== "concept")
+                    continue;
+                const query = { concept: op.name, space };
+                if (op.collection !== undefined)
+                    query.collection = op.collection;
+                try {
+                    await client.request({ method: "GET", path: "/v1/library/concept-vector", query });
+                }
+                catch (err) {
+                    throw new Error(`anchor '${name}': ${err.message}`);
+                }
+            }
+        }
+    }
+    /**
+     * Fuse {@link audioVectors} with per-anchor ``library.compare`` scoring — a live "which anchor does
+     * the room sound like right now" signal. ``anchors`` maps a name to anything the ``by`` grammar
+     * accepts (a bare string / {@link "../by".Asset} / ``by.*`` marker), **or an array** of those (a
+     * few-shot category, scored as the mean of its top-``topN`` members' calibrated compare scores;
+     * default ``topN: 1`` — the nearest member wins). Each frame's anchors are scored concurrently.
+     *
+     * Each {@link ScoredAudio} carries the calibrated ``scores`` plus ``mix`` (normalized to sum 1,
+     * uniform when every score is 0 — gate on ``max(scores)`` for silence). No smoothing — ease the
+     * stream with a {@link ../decider.Decider}. ``relay: true`` forwards to {@link audioVectors} (it
+     * relays the raw ``audio.vector``, not the computed scores). Concept anchors are validated once up
+     * front (a typo raises before any frame); a mid-stream compare failure re-throws named by anchor.
+     * Mirror of Python's ``audio_scores``.
+     */
+    async *audioScores(anchors, opts = {}) {
+        const client = this.deps.client;
+        const names = Object.keys(anchors);
+        const members = {};
+        for (const name of names)
+            members[name] = toAnchorMembers(anchors[name]);
+        const { space, model } = await this.resolveAudioSpace(opts.space, opts.model);
+        if (model === null) {
+            throw new Error(`the audio search space '${space}' has no model configured — pass model to audioScores()`);
+        }
+        await this.preflightConceptAnchors(members, space);
+        const topN = Math.max(1, opts.topN ?? 1);
+        for await (const vec of this.audioVectors({ space, model, relay: opts.relay })) {
+            const vectorOp = by.vector(vec.vector);
+            // Score every member of every anchor concurrently — a handful of compares is cheap vs. the ~10s
+            // window. Flatten to (name, op) pairs, then fold back into per-anchor top-N means below.
+            const flat = names.flatMap((name) => members[name].map((op) => ({ name, op })));
+            const results = await Promise.all(flat.map(async ({ name, op }) => {
+                try {
+                    const r = await client.library.compare(vectorOp, op, { space: vec.space });
+                    return r.score;
+                }
+                catch (err) {
+                    throw new Error(`anchor '${name}': ${err.message}`);
+                }
+            }));
+            const scores = {};
+            let i = 0;
+            for (const name of names) {
+                const n = members[name].length;
+                const top = results
+                    .slice(i, i + n)
+                    .sort((a, b) => b - a)
+                    .slice(0, topN);
+                scores[name] = top.reduce((a, b) => a + b, 0) / top.length;
+                i += n;
+            }
+            const total = Object.values(scores).reduce((a, b) => a + b, 0);
+            const mix = {};
+            for (const name of names) {
+                mix[name] = total > 0 ? scores[name] / total : 1 / names.length;
+            }
+            yield {
+                scores,
+                mix,
+                vector: vec.vector,
+                space: vec.space,
+                sequence: vec.sequence,
+                windowSeconds: vec.windowSeconds,
+                timestamp: vec.timestamp,
+            };
+        }
+    }
+    // ── Management (authenticated handles only) ──────────────────────────────
+    /** Rotate the connect code (owner only); updates ``connectCode`` and returns it. */
+    async rotateCode() {
+        const data = (await this.deps.rest(buildRoomRotateCode(this.id)));
+        this.connectCode = data.connect_code ?? this.connectCode;
+        return this.connectCode;
+    }
+    /** Delete the room for good (its connect code dies with it). */
+    async delete() {
+        await this.deps.rest({ method: "DELETE", path: `/v1/rooms/${this.id}` });
+    }
+    // The base tears the transport + recorders down; the recorder-registration seam is this class's,
+    // so it is dropped here (a listener outliving the handle would be notified about nothing).
+    teardown() {
+        // Base first: stopping the recorders fires the seam one last time, and only then is it dropped.
+        const done = super.teardown();
+        this.recorderListeners.clear();
+        return done;
+    }
+}
+//# sourceMappingURL=owned-room.js.map