hci-atrium 0.1.0

package/dist/rooms/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rooms/index.ts"],"names":[],"mappings":"AAAA;qEACqE;AAKrE,OAAO,EAAE,IAAI,EAAiB,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAA;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EACL,KAAK,gBAAgB,EACrB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAChG,OAAO,EAAE,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AAC5F,OAAO,EACL,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,QAAQ,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACjE,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,IAAI,EACJ,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC7E,OAAO,EACL,KAAK,YAAY,EACjB,iBAAiB,EACjB,KAAK,SAAS,EACd,cAAc,GACf,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACxF,YAAY,EACV,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,aAAa,EACb,aAAa,GACd,MAAM,gBAAgB,CAAA;AAEvB,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,iGAAiG;IACjG,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBtF"}

package/dist/rooms/index.js

@@ -0,0 +1,45 @@
+/** The live rooms surface — the {@link Room} handle, its audio codec, and the loginless
+ * {@link joinRoom} entry (no client needed, just a connect code). */
+import { DEFAULT_BASE_URL, readEnv } from "../env.js";
+import { raiseForStatus } from "../errors.js";
+import { httpFetch } from "../http.js";
+import { Room } from "./room.js";
+export { ArmedSet } from "./armed-set.js";
+export { 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";
+export { AUDIO_ROLE, AUDIO_SIGNAL, decodeAudioFrame, encodeAudioFrame, isAudioFrame, } from "./codec.js";
+export { OfferedCapture } from "./offer-capture.js";
+export { OfferedTranscription } from "./offer-transcription.js";
+export { mergeRoles, parseParticipant, participantMatches, } from "./participant.js";
+export { Recorder } from "./recorder.js";
+export { Room, } from "./room.js";
+export { AUDIO_SNIPPET_CONSUMER_ROLE, AUDIO_SNIPPET_MAGIC, AUDIO_SNIPPET_SOURCE_ROLE, AUDIO_SNIPPET_VERSION, AUDIO_SNIPPET_VERSION_2, CAPTURE_SOURCE_ROLE, decodeAudioSnippetFrame, isAudioSnippetFrame, } from "./snippet.js";
+export { RoomEventStream, readObserveRoster } from "./sse.js";
+export { OFFER_MAX_SOURCES, StandingSource, } from "./standing-source.js";
+export { TRANSCRIBER_SOURCE, Transcriber } from "./transcriber.js";
+/**
+ * Join a room by its connect code — **no account, no client**. Resolves the code to a room, then
+ * returns a live {@link Room} handle that can ``send`` / ``on`` / ``request`` / play / consume audio
+ * signals (but not manage the room — that needs the owner). Mirrors the Python SDK's ``join_room``.
+ */
+export async function joinRoom(code, opts = {}) {
+    const baseUrl = (opts.baseUrl ?? readEnv("ATRIUM_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const res = await httpFetch(`${baseUrl}/v1/rooms/resolve?code=${encodeURIComponent(code)}`);
+    if (!res.ok)
+        await raiseForStatus(res);
+    const data = (await res.json());
+    const deps = {
+        id: String(data.id),
+        connectCode: data.connect_code ?? code,
+        baseUrl,
+        identity: opts.identity,
+        announce: opts.announce,
+        requestTimeout: opts.requestTimeout,
+        reconnect: opts.reconnect,
+        transport: opts.transport,
+        WebSocketCtor: opts.WebSocketCtor,
+        fetchImpl: opts.fetchImpl,
+        signal: opts.signal,
+    };
+    return new Room(deps);
+}
+//# sourceMappingURL=index.js.map

package/dist/rooms/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rooms/index.ts"],"names":[],"mappings":"AAAA;qEACqE;AAErE,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,IAAI,EAAyC,MAAM,WAAW,CAAA;AAIvE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAEL,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,UAAU,EACV,YAAY,EAOZ,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAA+C,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAChG,OAAO,EAAE,oBAAoB,EAA+B,MAAM,0BAA0B,CAAA;AAC5F,OAAO,EACL,UAAU,EAGV,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,QAAQ,EAA2B,MAAM,eAAe,CAAA;AACjE,OAAO,EAIL,IAAI,GAML,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EAEvB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAkB,eAAe,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC7E,OAAO,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAA;AA0BxF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAwB,EAAE;IACrE,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,IAAI,gBAAgB,CAAC,CAAC,OAAO,CACtF,MAAM,EACN,EAAE,CACH,CAAA;IACD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,OAAO,0BAA0B,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC3F,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;IACtC,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA2C,CAAA;IACzE,MAAM,IAAI,GAAa;QACrB,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,WAAW,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI;QACtC,OAAO;QACP,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAA;IACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;AACvB,CAAC"}

package/dist/rooms/offer-capture.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The audio-capture standing service behind {@link ./room.Room.offerAudioCapture} — **session-less**:
+ * it writes into the **active recorder's** session (``room.record(into)`` is the single durable
+ * binding). The TypeScript port of Python's ``_AsyncOfferedCapture`` (aio.py). Engaged by a
+ * ``capture.start`` request, disengaged (finalizing every open recording) by ``capture.stop``, the
+ * room's close, or the bound recorder stopping.
+ *
+ * On ``capture.start`` it binds the **first** active recorder's session, subscribes the room's
+ * ``audio.snippet`` stream, and bridges each armed source's frames into one session recording per
+ * source via the chunk-append recording API. Collision-safe keys: name-else-cid, a same-name
+ * reconnect within grace resumes the file, two simultaneous same-name producers get their own
+ * (cid-suffixed) files. Exactly one recorder feeds audio — a second warns and is not double-written.
+ */
+import type { ShapedRequest } from "../shaping/index.js";
+import { type ActiveSource, type OfferDeps, StandingSource } from "./standing-source.js";
+/** The recorder a capture offer binds to — membership + liveness + the session its clips write into.
+ * A {@link ./recorder.Recorder} satisfies this structurally (``alive`` + ``into``). */
+export interface CaptureRecorder {
+    readonly alive: boolean;
+    readonly into: {
+        readonly id: string;
+    };
+}
+/** What the capture offer is wired with — the base {@link OfferDeps} plus the recorder seam + the
+ * authenticated REST caller for the chunked recording API. */
+export interface CaptureOfferDeps extends OfferDeps {
+    /** Perform a shaped REST request on the host's credential (the recording create/chunk/finalize). */
+    request(req: ShapedRequest): Promise<unknown>;
+    /** The recorders currently active on the room (membership + liveness) — availability + binding. */
+    activeRecorders(): CaptureRecorder[];
+    /** Subscribe to the room's recorder-set changes; returns an unsubscribe. */
+    onRecordersChanged(listener: () => void | Promise<void>): () => void;
+}
+export declare class OfferedCapture extends StandingSource {
+    protected readonly signal = "capture.available";
+    protected readonly logName = "capture offer";
+    protected readonly identityPrefix = "capture-offer";
+    private readonly captureDeps;
+    private readonly unsubscribeRecorders;
+    /** The recorder capture is writing under (bound at ``capture.start``); its session is derived from
+     * it, so the two can never drift. */
+    private boundRecorder;
+    /** source key (announced name when present, else connection id) → open recording id. */
+    private readonly recordings;
+    /** source connection id → the recording key it resolved to. */
+    private readonly sourceKey;
+    /** recording key → the connection id currently owning it. */
+    private readonly keyOwner;
+    /** v1 (id-less) recording key → its source_name (surfaces the null-source ``active`` entry). */
+    private readonly v1Open;
+    /** source key → consecutive failed recording-creates (reset by a success). */
+    private readonly createFailures;
+    /** source keys dropped after hitting the create-failure ceiling — later clips ignored. */
+    private readonly dead;
+    /** True once the "second recorder" warning fired for the current engagement (warn once). */
+    private warnedMulti;
+    constructor(deps: CaptureOfferDeps, opts?: {
+        maxSources?: number;
+    });
+    private get sessionId();
+    /** True ⇔ a recorder is active on the room **and** the bridge isn't dead from a terminal error. */
+    available(): boolean;
+    /** A v1 (id-less) source being recorded under the legacy all-arm shows as a null-source entry. */
+    protected activeExtra(): ActiveSource[];
+    /** Re-derive availability after the room's recorder set changed. If the bound recorder stopped,
+     * disengage; if a second recorder appeared while engaged, warn once (no double-write). */
+    private onRecordersChanged;
+    protected beforeArm(_armAll: boolean): Promise<CaptureRecorder[]>;
+    protected onEngage(ctx: unknown): void;
+    protected run(): Promise<void>;
+    /** Append one clip to its source's recording, opening the recording on the first clip. Only armed
+     * sources are bridged; a transient chunk failure is logged and skipped; a 401/403 propagates. */
+    private bridge;
+    /** Resolve (and memoize) the recording key for a source's first clip: RESUME a same-name key whose
+     * owner departed within grace; COLLIDE a same-name key owned by a different live connection to a
+     * cid-suffixed key. Returns ``null`` (warning once) if a new source would exceed the cap. */
+    private decideKey;
+    /** Create a source's recording, applying the create-failure circuit breaker. Returns the new
+     * recording id, or ``null`` if the create failed. A 401/403 propagates. */
+    private openRecording;
+    protected stopSource(cid: string): Promise<void>;
+    protected onGraceExpired(cid: string): Promise<void>;
+    stop(): Promise<void>;
+    /** Stop watching the recorder seam — call when the room is torn down for good. Named ``detach`` (not
+     * ``dispose``) so it isn't mistaken for the ``Symbol.dispose`` protocol: disposing an offer maps to
+     * {@link stop} (wind down + finalize), while ``detach`` only unsubscribes the recorder-changed hook. */
+    detach(): void;
+    private disengage;
+    /** The teardown body — the caller must already hold the lock. Cancel-before-clear: close the frame
+     * loop and await it *before* clearing the binding, so no straggling {@link bridge} runs against a
+     * half-cleared state. Skips the self-teardown when invoked from within the frame loop. */
+    private disengageLocked;
+    private finalizeOne;
+    private finalizeAll;
+}
+//# sourceMappingURL=offer-capture.d.ts.map

package/dist/rooms/offer-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offer-capture.d.ts","sourceRoot":"","sources":["../../src/rooms/offer-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAQxD,OAAO,EACL,KAAK,YAAY,EAGjB,KAAK,SAAS,EACd,cAAc,EACf,MAAM,sBAAsB,CAAA;AAE7B;uFACuF;AACvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CACvC;AAED;8DAC8D;AAC9D,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,oGAAoG;IACpG,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC7C,mGAAmG;IACnG,eAAe,IAAI,eAAe,EAAE,CAAA;IACpC,4EAA4E;IAC5E,kBAAkB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAA;CACrE;AAMD,qBAAa,cAAe,SAAQ,cAAc;IAChD,SAAS,CAAC,QAAQ,CAAC,MAAM,uBAAsB;IAC/C,SAAS,CAAC,QAAQ,CAAC,OAAO,mBAAkB;IAC5C,SAAS,CAAC,QAAQ,CAAC,cAAc,mBAAkB;IAEnD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkB;IAC9C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAY;IACjD;yCACqC;IACrC,OAAO,CAAC,aAAa,CAA+B;IACpD,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IACvD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,gGAAgG;IAChG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;IAC3D,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,4FAA4F;IAC5F,OAAO,CAAC,WAAW,CAAQ;gBAEf,IAAI,EAAE,gBAAgB,EAAE,IAAI,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAMtE,OAAO,KAAK,SAAS,GAEpB;IAED,mGAAmG;IAC1F,SAAS,IAAI,OAAO;IAK7B,kGAAkG;cAC/E,WAAW,IAAI,YAAY,EAAE;IAIhD;8FAC0F;YAC5E,kBAAkB;cAkBP,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;cAQ7D,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;cAa/B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BpC;qGACiG;YACnF,MAAM;IAoDpB;;iGAE6F;IAC7F,OAAO,CAAC,SAAS;IAoBjB;+EAC2E;YAC7D,aAAa;cAiCX,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cAoB7B,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;4GAEwG;IACxG,MAAM,IAAI,IAAI;YAIA,SAAS;IAIvB;;8FAE0F;YAC5E,eAAe;YA2Bf,WAAW;YAUX,WAAW;CAW1B"}

package/dist/rooms/offer-capture.js

@@ -0,0 +1,338 @@
+/**
+ * The audio-capture standing service behind {@link ./room.Room.offerAudioCapture} — **session-less**:
+ * it writes into the **active recorder's** session (``room.record(into)`` is the single durable
+ * binding). The TypeScript port of Python's ``_AsyncOfferedCapture`` (aio.py). Engaged by a
+ * ``capture.start`` request, disengaged (finalizing every open recording) by ``capture.stop``, the
+ * room's close, or the bound recorder stopping.
+ *
+ * On ``capture.start`` it binds the **first** active recorder's session, subscribes the room's
+ * ``audio.snippet`` stream, and bridges each armed source's frames into one session recording per
+ * source via the chunk-append recording API. Collision-safe keys: name-else-cid, a same-name
+ * reconnect within grace resumes the file, two simultaneous same-name producers get their own
+ * (cid-suffixed) files. Exactly one recorder feeds audio — a second warns and is not double-written.
+ */
+import { APIError } from "../errors.js";
+import { asError } from "../http.js";
+import { buildRecordingChunk, buildRecordingCreate, buildRecordingFinalize, } from "../shaping/rooms.js";
+import { decodeAudioSnippetFrame } from "./snippet.js";
+import { CAPTURE_CREATE_MAX_FAILURES, OFFER_MAX_SOURCES, StandingSource, } from "./standing-source.js";
+function isAuthError(err) {
+    return err instanceof APIError && (err.status === 401 || err.status === 403);
+}
+export class OfferedCapture extends StandingSource {
+    signal = "capture.available";
+    logName = "capture offer";
+    identityPrefix = "capture-offer";
+    captureDeps;
+    unsubscribeRecorders;
+    /** The recorder capture is writing under (bound at ``capture.start``); its session is derived from
+     * it, so the two can never drift. */
+    boundRecorder = null;
+    /** source key (announced name when present, else connection id) → open recording id. */
+    recordings = new Map();
+    /** source connection id → the recording key it resolved to. */
+    sourceKey = new Map();
+    /** recording key → the connection id currently owning it. */
+    keyOwner = new Map();
+    /** v1 (id-less) recording key → its source_name (surfaces the null-source ``active`` entry). */
+    v1Open = new Map();
+    /** source key → consecutive failed recording-creates (reset by a success). */
+    createFailures = new Map();
+    /** source keys dropped after hitting the create-failure ceiling — later clips ignored. */
+    dead = new Set();
+    /** True once the "second recorder" warning fired for the current engagement (warn once). */
+    warnedMulti = false;
+    constructor(deps, opts = {}) {
+        super(deps, opts.maxSources ?? OFFER_MAX_SOURCES);
+        this.captureDeps = deps;
+        this.unsubscribeRecorders = deps.onRecordersChanged(() => this.onRecordersChanged());
+    }
+    get sessionId() {
+        return this.boundRecorder?.into.id ?? null;
+    }
+    /** True ⇔ a recorder is active on the room **and** the bridge isn't dead from a terminal error. */
+    available() {
+        if (this.err !== null && !this.alive)
+            return false;
+        return this.captureDeps.activeRecorders().length > 0;
+    }
+    /** A v1 (id-less) source being recorded under the legacy all-arm shows as a null-source entry. */
+    activeExtra() {
+        return [...this.v1Open.values()].map((name) => ({ source: null, name }));
+    }
+    /** Re-derive availability after the room's recorder set changed. If the bound recorder stopped,
+     * disengage; if a second recorder appeared while engaged, warn once (no double-write). */
+    async onRecordersChanged() {
+        await this.lock.run(async () => {
+            if (this.boundRecorder !== null) {
+                const active = this.captureDeps.activeRecorders();
+                if (!active.includes(this.boundRecorder)) {
+                    await this.disengageLocked({});
+                }
+                else if (active.length > 1 && !this.warnedMulti) {
+                    this.warnedMulti = true;
+                    console.warn(`Atrium capture offer for room ${this.deps.roomId}: audio capture continues into the ` +
+                        "first recorder's session (a second recorder started)");
+                }
+            }
+        });
+        await this.broadcast();
+    }
+    async beforeArm(_armAll) {
+        const active = this.captureDeps.activeRecorders();
+        if (active.length === 0) {
+            throw new Error("no active recorder — call room.record(into=session) first");
+        }
+        return active;
+    }
+    onEngage(ctx) {
+        const active = ctx;
+        this.warnedMulti = active.length > 1;
+        if (this.warnedMulti) {
+            console.warn(`Atrium capture offer for room ${this.deps.roomId}: audio capture continues into the first ` +
+                "recorder's session (multiple recorders active)");
+        }
+        this.boundRecorder = active[0] ?? null;
+        this.stoppedReason = null;
+    }
+    async run() {
+        const ws = await this.openWs();
+        let threw = false;
+        try {
+            for await (const raw of this.frames()) {
+                const snippet = decodeAudioSnippetFrame(raw);
+                if (!snippet)
+                    continue; // a foreign / DSP binary frame — not ours
+                await this.bridge(snippet, snippet.source !== null ? this.nameFor(snippet.source) : null);
+            }
+        }
+        catch (err) {
+            threw = true;
+            this.err = asError(err);
+            console.error(`Atrium capture offer for room ${this.deps.roomId} died:`, err);
+            // Funnel through the single disengage path so we finalize what we opened *and* clear the
+            // binding. It's the running loop, so disengage skips the self-teardown wait.
+            await this.disengage({ fromRun: true });
+        }
+        if (!threw && this.codeRotated) {
+            console.info(`Atrium capture offer for room ${this.deps.roomId}: room code rotated; finalizing`);
+            await this.disengage({ reason: "code-rotated", fromRun: true });
+        }
+        // Natural frame-exhaustion (no rotation, no error) deliberately does NOT finalize — the recording
+        // stays open for an explicit capture.stop. Just stop the sweeper + close the socket.
+        this.stopSweeper();
+        ws.close();
+    }
+    /** Append one clip to its source's recording, opening the recording on the first clip. Only armed
+     * sources are bridged; a transient chunk failure is logged and skipped; a 401/403 propagates. */
+    async bridge(snippet, sourceName) {
+        const sessionId = this.sessionId;
+        if (sessionId === null)
+            return; // straggler after disengage (binding cleared)
+        const cid = snippet.source;
+        if (!this.armed.isArmed(cid))
+            return; // unarmed source — dropped at the demux
+        const isV1 = cid === null;
+        let resumed = false;
+        let key = isV1 ? null : (this.sourceKey.get(cid) ?? null);
+        if (key === null) {
+            if (isV1) {
+                key = sourceName || "default"; // a v1 frame has no id to key by — coalesce by name else a fixed key
+            }
+            else {
+                key = this.decideKey(cid, sourceName);
+                if (key === null)
+                    return; // cap exceeded — dropped (warned once)
+                resumed = this.recordings.has(key);
+            }
+        }
+        if (this.dead.has(key))
+            return;
+        let rid = this.recordings.get(key);
+        if (rid === undefined) {
+            const created = await this.openRecording(sessionId, key, sourceName, snippet.mimeType);
+            if (created === null)
+                return; // create failed (transient, or this source hit its ceiling)
+            // Re-check after the create's await: a per-source stop / disengage may have landed. If so, this
+            // recording is an orphan the stop path can't see — finalize it now rather than register it.
+            if (!this.armed.isArmed(cid) ||
+                (!isV1 && this.sourceKey.get(cid) !== key) ||
+                this.boundRecorder === null) {
+                await this.finalizeOne(created, sessionId);
+                return;
+            }
+            rid = created;
+            this.recordings.set(key, rid);
+            if (isV1)
+                this.v1Open.set(key, sourceName);
+            this.spawnBroadcast(); // a new source is now active (v1 surfaces the null entry)
+        }
+        else if (resumed) {
+            this.spawnBroadcast(); // a departed source resumed → active again
+        }
+        try {
+            await this.captureDeps.request(buildRecordingChunk(sessionId, rid, snippet.data, snippet.mimeType));
+        }
+        catch (err) {
+            if (isAuthError(err))
+                throw err;
+            console.warn(`Atrium capture: chunk upload for recording ${rid} failed — continuing with next clip:`, err);
+        }
+    }
+    /** Resolve (and memoize) the recording key for a source's first clip: RESUME a same-name key whose
+     * owner departed within grace; COLLIDE a same-name key owned by a different live connection to a
+     * cid-suffixed key. Returns ``null`` (warning once) if a new source would exceed the cap. */
+    decideKey(cid, sourceName) {
+        const candidate = sourceName || cid;
+        const owner = this.keyOwner.get(candidate);
+        let chosen;
+        if (owner === undefined || owner === cid)
+            chosen = candidate;
+        else if (this.isDeparted(owner))
+            chosen = candidate; // a same-name return within grace resumes
+        else
+            chosen = `${candidate}#${cid}`; // a different LIVE owner → own file (no cross-write)
+        if (!this.recordings.has(chosen) && this.recordings.size >= this.maxSources) {
+            this.warnCapped(cid);
+            return null;
+        }
+        const prior = this.keyOwner.get(chosen);
+        if (prior !== undefined && prior !== cid)
+            this.departed.delete(prior);
+        this.sourceKey.set(cid, chosen);
+        this.keyOwner.set(chosen, cid);
+        this.departed.delete(cid);
+        return chosen;
+    }
+    /** Create a source's recording, applying the create-failure circuit breaker. Returns the new
+     * recording id, or ``null`` if the create failed. A 401/403 propagates. */
+    async openRecording(sessionId, key, sourceName, contentType) {
+        let created;
+        try {
+            created = await this.captureDeps.request(buildRecordingCreate(sessionId, { sourceName, contentType }));
+        }
+        catch (err) {
+            if (isAuthError(err))
+                throw err;
+            const fails = (this.createFailures.get(key) ?? 0) + 1;
+            this.createFailures.set(key, fails);
+            if (fails >= CAPTURE_CREATE_MAX_FAILURES) {
+                this.dead.add(key);
+                this.createFailures.delete(key);
+                this.err = asError(err);
+                console.error(`Atrium capture: giving up on source ${JSON.stringify(key)} after ${fails} failed ` +
+                    "recording-creates:", err);
+            }
+            else {
+                console.warn("Atrium capture: could not open a recording — dropping this clip:", err);
+            }
+            return null;
+        }
+        this.createFailures.delete(key); // a success clears the streak
+        return String(created.id);
+    }
+    async stopSource(cid) {
+        await this.lock.run(async () => {
+            this.armed.disarm(cid);
+            const key = this.sourceKey.get(cid);
+            this.sourceKey.delete(cid);
+            let rid;
+            if (key !== undefined && this.keyOwner.get(key) === cid) {
+                this.keyOwner.delete(key);
+                rid = this.recordings.get(key);
+                this.recordings.delete(key);
+                this.createFailures.delete(key);
+                this.dead.delete(key);
+            }
+            this.departed.delete(cid);
+            this.cappedWarned.delete(cid);
+            if (rid !== undefined)
+                await this.finalizeOne(rid);
+        });
+        await this.broadcast();
+    }
+    async onGraceExpired(cid) {
+        await this.lock.run(async () => {
+            const key = this.sourceKey.get(cid);
+            if (key === undefined || this.keyOwner.get(key) !== cid)
+                return; // no open recording / re-owned
+            const rid = this.recordings.get(key);
+            this.recordings.delete(key);
+            this.keyOwner.delete(key);
+            for (const [c, k] of [...this.sourceKey])
+                if (k === key)
+                    this.sourceKey.delete(c);
+            this.createFailures.delete(key);
+            this.dead.delete(key);
+            if (rid !== undefined)
+                await this.finalizeOne(rid);
+        });
+    }
+    async stop() {
+        await this.disengage({});
+    }
+    /** Stop watching the recorder seam — call when the room is torn down for good. Named ``detach`` (not
+     * ``dispose``) so it isn't mistaken for the ``Symbol.dispose`` protocol: disposing an offer maps to
+     * {@link stop} (wind down + finalize), while ``detach`` only unsubscribes the recorder-changed hook. */
+    detach() {
+        this.unsubscribeRecorders();
+    }
+    async disengage(opts) {
+        await this.lock.run(() => this.disengageLocked(opts));
+    }
+    /** The teardown body — the caller must already hold the lock. Cancel-before-clear: close the frame
+     * loop and await it *before* clearing the binding, so no straggling {@link bridge} runs against a
+     * half-cleared state. Skips the self-teardown when invoked from within the frame loop. */
+    async disengageLocked(opts) {
+        if (opts.reason !== undefined)
+            this.stoppedReason = opts.reason;
+        if (!opts.fromRun) {
+            this.ws?.close(); // ends the frame loop (onEnd → end sentinel)
+            const running = this.runPromise;
+            this.runPromise = null;
+            if (running)
+                await running.catch(() => { });
+        }
+        this.stopSweeper();
+        await Promise.allSettled(this.bg);
+        this.bg.length = 0;
+        await this.finalizeAll(); // still bound → recordings finalize
+        this.boundRecorder = null; // clears the derived session — after finalize
+        this.armed.clear();
+        this.sourceKey.clear();
+        this.keyOwner.clear();
+        this.v1Open.clear();
+        this.departed.clear();
+        this.sourceNames.clear();
+        this.createFailures.clear();
+        this.dead.clear();
+        this.cappedWarned.clear();
+        this.warnedMulti = false;
+        this.clearLastBroadcast();
+        this.ws = null;
+    }
+    async finalizeOne(rid, sessionId) {
+        const sid = sessionId ?? this.sessionId;
+        if (sid === null)
+            return;
+        try {
+            await this.captureDeps.request(buildRecordingFinalize(sid, rid));
+        }
+        catch (err) {
+            console.warn(`Atrium capture: finalizing recording ${rid} failed:`, err);
+        }
+    }
+    async finalizeAll() {
+        const sid = this.sessionId;
+        if (sid === null) {
+            this.recordings.clear();
+            this.v1Open.clear();
+            return;
+        }
+        for (const rid of [...this.recordings.values()])
+            await this.finalizeOne(rid, sid);
+        this.recordings.clear();
+        this.v1Open.clear();
+    }
+}
+//# sourceMappingURL=offer-capture.js.map

package/dist/rooms/offer-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offer-capture.js","sourceRoot":"","sources":["../../src/rooms/offer-capture.ts"],"names":[],"mappings":"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"}

package/dist/rooms/offer-transcription.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The transcription standing service behind {@link ./room.Room.offerTranscription} — armed by a
+ * ``transcription.start`` request, wound down by ``transcription.stop`` or the room's close. The
+ * TypeScript port of Python's ``_AsyncOfferedTranscription`` + ``_publish_room_transcription`` (aio.py).
+ *
+ * Engage is **sender-scoped** (see {@link ./armed-set.ArmedSet}): only armed sources are transcribed
+ * — an unarmed source's frames are dropped at the demux (no engine spawns). While engaged it
+ * subscribes the room's ``audio.snippet`` stream, demuxes frames per source, and runs one
+ * transcription engine per source (the same engine as {@link ./room.Room.transcribe}), stamping each
+ * ``transcript.*`` signal's payload with the source's connection id and roster-resolved
+ * ``source_name``. Up to ``maxSources`` sources; a departed source's engine is reaped promptly.
+ */
+import type { Transcript } from "../models.js";
+import { type ActiveSource, type OfferDeps, StandingSource } from "./standing-source.js";
+/** What the transcription offer is wired with — the base {@link OfferDeps} plus the shared engine. */
+export interface TranscriptionOfferDeps extends OfferDeps {
+    /** The client's shared live-transcription engine (streaming when the backend offers it, per-clip
+     * batch otherwise) — one input iterable per source. */
+    engine(clips: AsyncIterable<ArrayBuffer>, opts: {
+        model?: string;
+        language?: string;
+        signal?: AbortSignal;
+    }): AsyncIterable<Transcript>;
+}
+export declare class OfferedTranscription extends StandingSource {
+    protected readonly signal = "transcription.available";
+    protected readonly logName = "transcription offer";
+    protected readonly identityPrefix = "transcription-offer";
+    private readonly engineFn;
+    private readonly model?;
+    private readonly language?;
+    private readonly queues;
+    private readonly engines;
+    private readonly aborts;
+    private reaped;
+    private readonly stalled;
+    constructor(deps: TranscriptionOfferDeps, opts?: {
+        model?: string;
+        language?: string;
+        maxSources?: number;
+    });
+    /** A v1 (id-less) source being transcribed under an all-arm surfaces as a null-source entry. */
+    protected activeExtra(): ActiveSource[];
+    protected run(): Promise<void>;
+    /** Route one clip to its source's engine — dropping it if the source is unarmed or past the cap,
+     * and spawning the engine on a source's first clip. */
+    private admit;
+    private spawnEngine;
+    /** Run the engine over one source's clip queue and publish each result — the shared
+     * {@link publishRoomTranscripts} with per-source attribution, published over the REST ``/signal``
+     * POST (so the ephemeral partial hint survives) as ``source: "transcriber"``. */
+    private publishTranscription;
+    /** Hand one clip to a source's engine, dropping the oldest queued clip if the engine has stalled.
+     * Warns once per source per stall episode. */
+    private enqueue;
+    /** On leave, cancel that source's engine immediately (mirror of Python's ``engine.cancel()``):
+     * abort its signal and drop its buffered clips, so no captions publish for a source that has left
+     * (consent-relevant). The reaped engine is awaited at teardown (the base handles the rest). */
+    protected onPresenceSource(event: "join" | "leave", cid: string): void;
+    protected stopSource(source: string): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=offer-transcription.d.ts.map

package/dist/rooms/offer-transcription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offer-transcription.d.ts","sourceRoot":"","sources":["../../src/rooms/offer-transcription.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,EACL,KAAK,YAAY,EAGjB,KAAK,SAAS,EACd,cAAc,EACf,MAAM,sBAAsB,CAAA;AAG7B,sGAAsG;AACtG,MAAM,WAAW,sBAAuB,SAAQ,SAAS;IACvD;2DACuD;IACvD,MAAM,CACJ,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,EACjC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAChE,aAAa,CAAC,UAAU,CAAC,CAAA;CAC7B;AA6CD,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,SAAS,CAAC,QAAQ,CAAC,MAAM,6BAA4B;IACrD,SAAS,CAAC,QAAQ,CAAC,OAAO,yBAAwB;IAClD,SAAS,CAAC,QAAQ,CAAC,cAAc,yBAAwB;IAEzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;IAGlE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;IACnE,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAGjD,IAAI,EAAE,sBAAsB,EAC5B,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAQvE,gGAAgG;cAC7E,WAAW,IAAI,YAAY,EAAE;cAIhC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BpC;2DACuD;IACvD,OAAO,CAAC,KAAK;IAmBb,OAAO,CAAC,WAAW;IAanB;;qFAEiF;IACjF,OAAO,CAAC,oBAAoB;IAqB5B;kDAC8C;IAC9C,OAAO,CAAC,OAAO;IAcf;;mGAE+F;cAC5E,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;cAmB/D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAU5B"}