@memberjunction/ai-bridge-livekit 0.0.1 → 5.41.0

package/README.md

@@ -1,45 +1,130 @@
 # @memberjunction/ai-bridge-livekit
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/ai-bridge-livekit`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+The **LiveKit** Realtime Bridge driver — the **MJ-native multi-party room**. Unlike every other bridge
+in MemberJunction's Realtime Bridges program (which connect **out** to a 3rd-party meeting platform like
+Zoom/Teams/Meet or a telephony carrier), LiveKit is a **self-hosted WebRTC SFU that MJ runs itself**. The
+architecture treats a Zoom meeting and an MJ-native LiveKit room **identically** — both are multi-party
+media transports — so this is "*another bridge, not a special build.*"
+
+It connects the one realtime agent engine to a **LiveKit room** as a bot participant: bidirectional
+audio (and full video/screen), a per-participant diarized roster, room-admin mute, data-channel chat, and
+a **Meeting Controls** facilitator channel — all behind an injectable LiveKit room SDK seam so the driver
+builds and unit-tests with **no network and no real LiveKit SDK**.
+
+See the [Realtime Bridges Guide](../../../../guides/REALTIME_BRIDGES_GUIDE.md) and
+[`/plans/realtime/realtime-bridges-architecture.md`](../../../../plans/realtime/realtime-bridges-architecture.md)
+(§4c multi-party / MJ-native room, §3 provider abstraction, §4b channels) for the full architecture.
+
+## Install
+
+```bash
+npm install @memberjunction/ai-bridge-livekit
+```
+
+## Self-hosted vs. connecting out
+
+| | The other bridges (Zoom, Teams, Meet, Webex, Slack, Discord, Twilio…) | **LiveKit (this package)** |
+|---|---|---|
+| Who owns the room | a 3rd-party platform | **MJ — self-hosted SFU** |
+| How you join | a join URL / number you were handed | a room URL + a **token MJ mints** |
+| Bot admission | per-platform review/quirks | none — MJ controls the room |
+| Use case | meet the customer where they already are | an MJ-native multi-party experience (e.g. embedded in Explorer) |
+
+The same multi-party machinery (§4c) works either way: put **1+ agents into a shared room** and the room
+itself is the shared media plane.
+
+## What it provides
+
+- **`LiveKitBridge`** — `@RegisterClass(BaseRealtimeBridge, 'LiveKitBridge')`. The `MJ: AI Bridge
+  Providers` row with `DriverClass = 'LiveKitBridge'` resolves to this driver via the `ClassFactory`.
+  Implements the four `BaseRealtimeBridge` abstracts (`Connect` / `Disconnect` / `SendMedia` / `OnMedia`)
+  and the capability-gated virtuals LiveKit supports (`GetParticipants`, `OnParticipantChange`), plus
+  `GetMeetingControlsEventSource` for the facilitator channel and a `SendDataMessage` helper.
+- **`ILiveKitRoomSdk`** — the **injectable seam** the driver depends on instead of the real SDK.
+- **`LiveKitMeetingControlsEventSource`** — adapts the seam's roster / speaking / mute into the bridge's
+  `IBridgeMeetingControlsEventSource`, so the engine wires the Meeting Controls channel.
+
+## Capability coverage (the LiveKit seed row)
+
+| Capability | Status |
+|---|---|
+| On-demand join | ✅ |
+| Audio in / out | ✅ |
+| Video in / out | ✅ (LiveKit does full A/V) |
+| Screen in / out | ✅ (full screen share) |
+| Speaker diarization (per-participant tracks → labels) | ✅ — **native**, the SFU delivers tracks per participant |
+| Room-admin mute (Meeting Controls) | ✅ |
+| Data-channel chat | ✅ |
+| Scheduled / invite / native-invite join, DTMF / transfer / recording | ➖ not LiveKit-room features — the gated base methods throw `BridgeCapabilityNotSupportedError` |
+
+Capability gating is two-layer (defense-in-depth): the engine checks the provider's `SupportedFeatures`
+first, and the driver re-asserts each flag with `RequireFeature` at the top of its overrides.
+
+## The LiveKit room SDK seam (`ILiveKitRoomSdk`)
+
+The driver never imports the real LiveKit SDK. It depends only on this minimal interface:
+
+```typescript
+export interface ILiveKitRoomSdk {
+    connect(args: LiveKitConnectArgs): Promise<LiveKitConnectResult>;       // roomUrl + signed token → join as bot
+    disconnect(): Promise<void>;
+    publishAudioFrame(pcm: ArrayBuffer): void;                              // agent's voice out
+    onAudioTrack(cb: (frame: LiveKitAudioFrame) => void): void;            // per-participant audio in (diarization)
+    publishVideoFrame(frame: ArrayBuffer): void;                            // full video out
+    publishScreenFrame(frame: ArrayBuffer): void;                           // full screen share out
+    onParticipantJoin(cb: (p: LiveKitParticipant) => void): void;
+    onParticipantLeave(cb: (id: string) => void): void;
+    getParticipants(): Promise<LiveKitParticipant[]>;
+    sendDataMessage(text: string): Promise<void>;                           // data-channel chat
+    onDisconnected(cb: () => void): void;
+}
+```
+
+**Production binding (TODO at deployment):** bind this to `livekit-server-sdk` (token minting / room
+admin) plus a room client (the Node WebRTC participant, e.g. `@livekit/rtc-node`). The adapter is thin
+and the driver/tests do not change. None of the SDK types leak into this package. Until a real factory is
+bound via `LiveKitBridge.SetSdkFactory(...)`, `Connect` throws an explicit "bind the real LiveKit SDK"
+error.
+
+## Echo / self-audio
+
+A LiveKit SFU **never delivers a participant its own published track back** — the bot does not hear its
+own voice, so no echo gate is needed. This is exactly the property the multi-party model relies on
+(§4c): each agent in a room hears the *others'* mix natively, never itself, so two agents can converse
+without a transcript-relay hack.
+
+## Usage
+
+```typescript
+import { LiveKitBridge } from '@memberjunction/ai-bridge-livekit';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+
+// The engine resolves the driver by DriverClass via the ClassFactory; you do not new it up directly.
+// In production, bind the real SDK factory once at boot:
+//   (resolved per provider config) — LiveKitBridge instances call SetSdkFactory with a real adapter.
+
+const active = await AIBridgeEngine.Instance.StartBridgeSession({
+    AgentSessionID: sessionId,
+    Provider: liveKitProvider,            // MJ: AI Bridge Providers row, DriverClass='LiveKitBridge'
+    RealtimeSession: realtimeSession,     // injected IRealtimeSession
+    Address: 'wss://livekit.myorg.com',   // the MJ-native room server
+    Configuration: { AccessToken: signedToken, BotDisplayName: 'Sage' },
+    MetadataProvider: provider,
+    ContextUser: user,
+});
+```
+
+For multiple agents in one LiveKit room, register each session with the engine's room coordinator — see
+the [Multi-party section of the guide](../../../../guides/REALTIME_BRIDGES_GUIDE.md) and
+`MultiAgentRoomCoordinator` in `@memberjunction/ai-bridge-server`.
+
+## Testing
+
+`FakeLiveKitRoomSdk` (in the test file) implements `ILiveKitRoomSdk` in memory with drive helpers and
+capture sinks — connect/disconnect, audio in→`OnMedia` (speaker labels) + out→track, video/screen out,
+participant join/leave→roster, speaking attribution, data-channel chat, and capability gating. **24
+tests, no network.** Run with `npm test`.
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './livekit-sdk.js';
+export * from './livekit-meeting-controls.js';
+export * from './livekit-bridge.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './livekit-sdk.js';
+export * from './livekit-meeting-controls.js';
+export * from './livekit-bridge.js';
+import { LoadLiveKitBridge } from './livekit-bridge.js';
+// Static reference so bundlers cannot tree-shake the @RegisterClass(BaseRealtimeBridge, 'LiveKitBridge')
+// registration. Calling the no-op here keeps the driver resolvable by the engine's ClassFactory.
+LoadLiveKitBridge();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,yGAAyG;AACzG,iGAAiG;AACjG,iBAAiB,EAAE,CAAC"}

package/dist/livekit-bridge.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview `LiveKitBridge` — the **MJ-native multi-party room** Realtime Bridge driver. Unlike
+ * every other bridge (which connects OUT to a 3rd-party meeting/telephony platform), LiveKit is a
+ * **self-hosted WebRTC SFU that MJ runs itself** — the "MJ-native room"
+ * (`/plans/realtime/realtime-bridges-architecture.md` §4c). The architecture treats a Zoom meeting and
+ * an MJ-native LiveKit room **identically** — both are multi-party media transports — so this is
+ * "*another bridge, not a special build*."
+ *
+ * Implements the {@link BaseRealtimeBridge} contract against an injectable {@link ILiveKitRoomSdk} seam
+ * so it builds + unit-tests with NO network and NO real LiveKit SDK (the Zoom `SetSdkFactory`
+ * testability pattern).
+ *
+ * LiveKit capability coverage (per the §4c / §8 seed row): on-demand join, **full** audio/video/screen
+ * in+out (LiveKit does the lot), and per-participant diarization (`SpeakerDiarization`) — the SFU
+ * delivers tracks per participant, so speaker labels come free. No scheduled/invite/telephony features.
+ * Those virtual base methods keep throwing `BridgeCapabilityNotSupportedError`.
+ *
+ * ## Echo / self-audio
+ * A LiveKit SFU **never delivers a participant its own published track back**, so the bot does not hear
+ * its own voice — no echo gate is required (see {@link wireInboundAudio}). This is exactly the property
+ * §4c relies on for putting **multiple agents in one room**: each agent hears the *others'* mixed audio
+ * natively, not its own, so two agents converse without a transcript-relay hack.
+ *
+ * @module @memberjunction/ai-bridge-livekit
+ * @author MemberJunction.com
+ */
+import { BaseRealtimeBridge, BridgeConnectResult, BridgeDisconnectReason, BridgeMediaFrame, BridgeMediaTrackKind, BridgeParticipantInfo, RealtimeBridgeContext, IBridgeMeetingControlsEventSource } from '@memberjunction/ai-bridge-base';
+import { LiveKitRoomSdkFactory } from './livekit-sdk.js';
+/**
+ * The `DriverClass` key {@link LiveKitBridge} registers under. A `MJ: AI Bridge Providers` row with
+ * `DriverClass = 'LiveKitBridge'` resolves to this driver via the `ClassFactory`.
+ */
+export declare const LIVEKIT_BRIDGE_DRIVER_CLASS = "LiveKitBridge";
+/**
+ * Realtime Bridge driver for the **MJ-native LiveKit room**.
+ *
+ * Construct the driver with the default constructor (the engine's `ClassFactory` path) — it lazily
+ * builds the LiveKit room SDK from the {@link sdkFactory} at {@link Connect} time. Tests inject a
+ * `FakeLiveKitRoomSdk` by overriding the factory via {@link SetSdkFactory} (the creation seam) before
+ * connecting.
+ *
+ * Registered via `@RegisterClass(BaseRealtimeBridge, 'LiveKitBridge')`.
+ */
+export declare class LiveKitBridge extends BaseRealtimeBridge {
+    /** The live LiveKit SDK seam for this session, created at {@link Connect}. */
+    private sdk;
+    /** The bot's own participant identity in the joined room (set at {@link Connect}). */
+    private botIdentity;
+    /** The inbound-media handler registered via {@link OnMedia}; raw audio frames are forwarded to it. */
+    private mediaHandler?;
+    /** The roster-change handler registered via {@link OnParticipantChange}. */
+    private participantHandler?;
+    /** The Meeting Controls event source for this session (only when diarization is supported). */
+    private meetingControls;
+    /**
+     * The SDK creation seam. Defaults to a factory that throws an explicit "bind the real LiveKit SDK"
+     * error, since this package ships WITHOUT the real SDK adapter (a deployment concern). Production
+     * sets a real factory via {@link SetSdkFactory}; tests inject a `FakeLiveKitRoomSdk`.
+     */
+    private sdkFactory;
+    /**
+     * Sets the {@link LiveKitRoomSdkFactory} this driver uses to construct its SDK seam at connect — the
+     * creation seam (mirroring Zoom's `SetSdkFactory`). Production binds the real LiveKit room SDK
+     * adapter here; tests inject a `FakeLiveKitRoomSdk`.
+     *
+     * @param factory The factory that builds the {@link ILiveKitRoomSdk} for a session.
+     */
+    SetSdkFactory(factory: LiveKitRoomSdkFactory): void;
+    /**
+     * Connects to the MJ-native LiveKit room and brings the bot online. Captures the capability context,
+     * builds the SDK from the {@link sdkFactory}, wires the inbound per-participant audio path and
+     * room-disconnected callback, connects, and (when the provider diarizes) constructs + seeds the
+     * Meeting Controls event source.
+     *
+     * @param ctx The bridge context (features, provider name, the room URL as `Address`, config carrying
+     *   the signed access token).
+     * @returns The bot identity + room (external connection) identifiers, persisted by the engine.
+     */
+    Connect(ctx: RealtimeBridgeContext): Promise<BridgeConnectResult>;
+    /**
+     * Disconnects from the LiveKit room and releases all SDK resources. Tolerant of teardown errors.
+     *
+     * @param _reason Why the disconnect happened (LiveKit teardown is uniform; the bot simply leaves).
+     */
+    Disconnect(_reason: BridgeDisconnectReason): Promise<void>;
+    /**
+     * Sends an outbound media frame into the room. LiveKit does the FULL media set, so audio, video, and
+     * screen are all published on their respective tracks (gated by the directional capability flags —
+     * the realtime models light audio first, video/screen ride the same path once a model emits them).
+     *
+     * @param track The outbound track the frame targets.
+     * @param frame The media frame to send.
+     */
+    SendMedia(track: BridgeMediaTrackKind, frame: BridgeMediaFrame): void;
+    /**
+     * Registers the inbound-media handler. The driver forwards each raw per-participant audio frame
+     * (with its speaker identity) to this handler; the engine routes it to `IRealtimeSession.SendInput`.
+     *
+     * @param handler Invoked with each inbound media frame.
+     */
+    OnMedia(handler: (frame: BridgeMediaFrame) => void): void;
+    /**
+     * Returns the current LiveKit participant roster (gated by `SpeakerDiarization`). Re-asserts the
+     * flag (defense-in-depth) so even an engine-bypassing caller cannot pull a roster a disabled
+     * provider forbids.
+     *
+     * @returns The current participants.
+     * @throws {BridgeCapabilityNotSupportedError} when diarization is not enabled for the provider.
+     */
+    GetParticipants(): Promise<BridgeParticipantInfo[]>;
+    /**
+     * Registers a roster-change handler (gated by `SpeakerDiarization`). The driver fires it from the
+     * SDK's participant join/leave stream with the full current roster.
+     *
+     * @param handler Invoked with the updated participant list on each change.
+     * @throws {BridgeCapabilityNotSupportedError} when diarization is not enabled.
+     */
+    OnParticipantChange(handler: (participants: BridgeParticipantInfo[]) => void): void;
+    /**
+     * Returns the LiveKit Meeting Controls event source for this session (roster · speaking · mute), or
+     * `null` when diarization is off (no roster to facilitate). The engine wires the Meeting Controls
+     * channel from this.
+     */
+    GetMeetingControlsEventSource(): IBridgeMeetingControlsEventSource | null;
+    /**
+     * Sends a message on the LiveKit data channel — the room-native "chat". Exposed for the channel
+     * plane / turn-taking hybrid mode (the social-cost-free "raise hand"). Best-effort — a failure is
+     * logged, never fatal.
+     *
+     * @param text The data/chat message to send.
+     */
+    SendDataMessage(text: string): Promise<void>;
+    /** The bot's participant identity in the joined room (or `null` before {@link Connect}). */
+    get BotIdentity(): string | null;
+    /**
+     * Wires the SDK's inbound per-participant audio callback to a diarized inbound
+     * {@link BridgeMediaFrame}. The SFU never echoes the bot's own audio, so no self-audio gate is
+     * needed; the frame's `SpeakerLabel` is the source participant identity.
+     */
+    private wireInboundAudio;
+    /**
+     * Wires the SDK's participant join/leave streams ONCE (the driver is the single owner; the SDK seam
+     * is latest-handler-wins). Each roster change fans out to both the driver's own roster-change
+     * handler and the Meeting Controls source.
+     */
+    private wireRoster;
+    /** Pulls the current roster from the SDK and fans it out to both the participant handler + Meeting Controls. */
+    private refreshRoster;
+    /** Handles the SDK's room-disconnected signal: surface an empty roster so the engine sees everyone gone. */
+    private handleRoomDisconnected;
+    /** Builds the SDK connect args from the bridge context (Address is the room URL; token from config). */
+    private buildConnectArgs;
+    /** Returns the bytes of an outbound media frame, preferring the binary payload. */
+    private framePcm;
+    /** Decodes a base64 payload to an `ArrayBuffer` (Node `Buffer` fast path, `atob` fallback). */
+    private decodeBase64;
+}
+/**
+ * Tree-shaking-prevention loader. Modern bundlers cannot see the `@RegisterClass` dynamic registration
+ * of {@link LiveKitBridge} and may eliminate it. Import and call this no-op from a static code path
+ * (the package entry point does) so the `ClassFactory` can resolve `'LiveKitBridge'`.
+ */
+export declare function LoadLiveKitBridge(): void;
+//# sourceMappingURL=livekit-bridge.d.ts.map

package/dist/livekit-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit-bridge.d.ts","sourceRoot":"","sources":["../src/livekit-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EACH,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EAErB,qBAAqB,EACrB,iCAAiC,EACpC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAEH,qBAAqB,EAKxB,MAAM,eAAe,CAAC;AAGvB;;;GAGG;AACH,eAAO,MAAM,2BAA2B,kBAAkB,CAAC;AA8B3D;;;;;;;;;GASG;AACH,qBACa,aAAc,SAAQ,kBAAkB;IACjD,8EAA8E;IAC9E,OAAO,CAAC,GAAG,CAAgC;IAE3C,sFAAsF;IACtF,OAAO,CAAC,WAAW,CAAuB;IAE1C,sGAAsG;IACtG,OAAO,CAAC,YAAY,CAAC,CAAoC;IAEzD,4EAA4E;IAC5E,OAAO,CAAC,kBAAkB,CAAC,CAAkD;IAE7E,+FAA+F;IAC/F,OAAO,CAAC,eAAe,CAAkD;IAEzE;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAKhB;IAEF;;;;;;OAMG;IACI,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAM1D;;;;;;;;;OASG;IACU,OAAO,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA2B9E;;;;OAIG;IACU,UAAU,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvE;;;;;;;OAOG;IACI,SAAS,CAAC,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IA4B5E;;;;;OAKG;IACI,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IAMhE;;;;;;;OAOG;IACmB,eAAe,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;IASzE;;;;;;OAMG;IACa,mBAAmB,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,qBAAqB,EAAE,KAAK,IAAI,GAAG,IAAI;IAKnG;;;;OAIG;IACa,6BAA6B,IAAI,iCAAiC,GAAG,IAAI;IAMzF;;;;;;OAMG;IACU,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWzD,4FAA4F;IAC5F,IAAW,WAAW,IAAI,MAAM,GAAG,IAAI,CAEtC;IAID;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAKlB,gHAAgH;YAClG,aAAa;IAU3B,4GAA4G;IAC5G,OAAO,CAAC,sBAAsB;IAK9B,wGAAwG;IACxG,OAAO,CAAC,gBAAgB;IASxB,mFAAmF;IACnF,OAAO,CAAC,QAAQ;IAUhB,+FAA+F;IAC/F,OAAO,CAAC,YAAY;CAcvB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/livekit-bridge.js

@@ -0,0 +1,353 @@
+/**
+ * @fileoverview `LiveKitBridge` — the **MJ-native multi-party room** Realtime Bridge driver. Unlike
+ * every other bridge (which connects OUT to a 3rd-party meeting/telephony platform), LiveKit is a
+ * **self-hosted WebRTC SFU that MJ runs itself** — the "MJ-native room"
+ * (`/plans/realtime/realtime-bridges-architecture.md` §4c). The architecture treats a Zoom meeting and
+ * an MJ-native LiveKit room **identically** — both are multi-party media transports — so this is
+ * "*another bridge, not a special build*."
+ *
+ * Implements the {@link BaseRealtimeBridge} contract against an injectable {@link ILiveKitRoomSdk} seam
+ * so it builds + unit-tests with NO network and NO real LiveKit SDK (the Zoom `SetSdkFactory`
+ * testability pattern).
+ *
+ * LiveKit capability coverage (per the §4c / §8 seed row): on-demand join, **full** audio/video/screen
+ * in+out (LiveKit does the lot), and per-participant diarization (`SpeakerDiarization`) — the SFU
+ * delivers tracks per participant, so speaker labels come free. No scheduled/invite/telephony features.
+ * Those virtual base methods keep throwing `BridgeCapabilityNotSupportedError`.
+ *
+ * ## Echo / self-audio
+ * A LiveKit SFU **never delivers a participant its own published track back**, so the bot does not hear
+ * its own voice — no echo gate is required (see {@link wireInboundAudio}). This is exactly the property
+ * §4c relies on for putting **multiple agents in one room**: each agent hears the *others'* mixed audio
+ * natively, not its own, so two agents converse without a transcript-relay hack.
+ *
+ * @module @memberjunction/ai-bridge-livekit
+ * @author MemberJunction.com
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { LogError } from '@memberjunction/core';
+import { BaseRealtimeBridge, } from '@memberjunction/ai-bridge-base';
+import { LiveKitMeetingControlsEventSource } from './livekit-meeting-controls.js';
+/**
+ * The `DriverClass` key {@link LiveKitBridge} registers under. A `MJ: AI Bridge Providers` row with
+ * `DriverClass = 'LiveKitBridge'` resolves to this driver via the `ClassFactory`.
+ */
+export const LIVEKIT_BRIDGE_DRIVER_CLASS = 'LiveKitBridge';
+/**
+ * Maps a LiveKit participant role to the bridge's {@link BridgeParticipantRole}. The bot (`IsLocal`) is
+ * surfaced as `'Agent'`.
+ */
+function mapParticipantRole(role, isLocal) {
+    if (isLocal) {
+        return 'Agent';
+    }
+    switch (role) {
+        case 'Host':
+            return 'Host';
+        case 'CoHost':
+            return 'CoHost';
+        default:
+            return 'Participant';
+    }
+}
+/** Maps a LiveKit participant onto the bridge's {@link BridgeParticipantInfo}. */
+function toBridgeParticipant(p) {
+    return {
+        ExternalId: p.Identity,
+        DisplayName: p.DisplayName,
+        Role: mapParticipantRole(p.Role, p.IsLocal),
+        IsAgent: p.IsLocal === true,
+    };
+}
+/**
+ * Realtime Bridge driver for the **MJ-native LiveKit room**.
+ *
+ * Construct the driver with the default constructor (the engine's `ClassFactory` path) — it lazily
+ * builds the LiveKit room SDK from the {@link sdkFactory} at {@link Connect} time. Tests inject a
+ * `FakeLiveKitRoomSdk` by overriding the factory via {@link SetSdkFactory} (the creation seam) before
+ * connecting.
+ *
+ * Registered via `@RegisterClass(BaseRealtimeBridge, 'LiveKitBridge')`.
+ */
+let LiveKitBridge = class LiveKitBridge extends BaseRealtimeBridge {
+    constructor() {
+        super(...arguments);
+        /** The live LiveKit SDK seam for this session, created at {@link Connect}. */
+        this.sdk = null;
+        /** The bot's own participant identity in the joined room (set at {@link Connect}). */
+        this.botIdentity = null;
+        /** The Meeting Controls event source for this session (only when diarization is supported). */
+        this.meetingControls = null;
+        /**
+         * The SDK creation seam. Defaults to a factory that throws an explicit "bind the real LiveKit SDK"
+         * error, since this package ships WITHOUT the real SDK adapter (a deployment concern). Production
+         * sets a real factory via {@link SetSdkFactory}; tests inject a `FakeLiveKitRoomSdk`.
+         */
+        this.sdkFactory = () => {
+            throw new Error('LiveKitBridge has no LiveKit room SDK bound. Call LiveKitBridge.SetSdkFactory(...) with a factory ' +
+                'that builds an ILiveKitRoomSdk over the real livekit-server-sdk + a room client, or inject a fake in tests.');
+        };
+    }
+    /**
+     * Sets the {@link LiveKitRoomSdkFactory} this driver uses to construct its SDK seam at connect — the
+     * creation seam (mirroring Zoom's `SetSdkFactory`). Production binds the real LiveKit room SDK
+     * adapter here; tests inject a `FakeLiveKitRoomSdk`.
+     *
+     * @param factory The factory that builds the {@link ILiveKitRoomSdk} for a session.
+     */
+    SetSdkFactory(factory) {
+        this.sdkFactory = factory;
+    }
+    // ── Abstract — every bridge MUST implement ───────────────────────────────────────
+    /**
+     * Connects to the MJ-native LiveKit room and brings the bot online. Captures the capability context,
+     * builds the SDK from the {@link sdkFactory}, wires the inbound per-participant audio path and
+     * room-disconnected callback, connects, and (when the provider diarizes) constructs + seeds the
+     * Meeting Controls event source.
+     *
+     * @param ctx The bridge context (features, provider name, the room URL as `Address`, config carrying
+     *   the signed access token).
+     * @returns The bot identity + room (external connection) identifiers, persisted by the engine.
+     */
+    async Connect(ctx) {
+        this.applyContext(ctx);
+        this.RequireFeature('AudioIn'); // a LiveKit room bridge requires bidirectional audio at minimum
+        this.RequireFeature('AudioOut');
+        this.sdk = this.sdkFactory(ctx.Configuration);
+        this.wireInboundAudio(this.sdk);
+        this.sdk.onDisconnected(() => this.handleRoomDisconnected());
+        // Roster diarization is native to LiveKit (per-participant tracks); only stand up the Meeting
+        // Controls source when the provider advertises it (the engine also gates on this flag).
+        if (this.features.SpeakerDiarization === true) {
+            this.meetingControls = new LiveKitMeetingControlsEventSource(this.sdk);
+        }
+        // The driver owns the single SDK subscription set and fans out to BOTH its own roster handler
+        // and the Meeting Controls source (the SDK seam is latest-handler-wins, so there is one owner).
+        this.wireRoster(this.sdk);
+        const result = await this.sdk.connect(this.buildConnectArgs(ctx));
+        this.botIdentity = result.BotIdentity;
+        // Seed the initial roster now that the bot has joined.
+        await this.refreshRoster(this.sdk);
+        return { BotParticipantId: result.BotIdentity, ExternalConnectionId: result.RoomName };
+    }
+    /**
+     * Disconnects from the LiveKit room and releases all SDK resources. Tolerant of teardown errors.
+     *
+     * @param _reason Why the disconnect happened (LiveKit teardown is uniform; the bot simply leaves).
+     */
+    async Disconnect(_reason) {
+        const sdk = this.sdk;
+        this.sdk = null;
+        this.botIdentity = null;
+        this.meetingControls = null;
+        this.mediaHandler = undefined;
+        this.participantHandler = undefined;
+        if (sdk) {
+            try {
+                await sdk.disconnect();
+            }
+            catch (err) {
+                LogError(`[LiveKitBridge] disconnect() failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * Sends an outbound media frame into the room. LiveKit does the FULL media set, so audio, video, and
+     * screen are all published on their respective tracks (gated by the directional capability flags —
+     * the realtime models light audio first, video/screen ride the same path once a model emits them).
+     *
+     * @param track The outbound track the frame targets.
+     * @param frame The media frame to send.
+     */
+    SendMedia(track, frame) {
+        if (!this.sdk) {
+            return; // not connected — drop
+        }
+        const bytes = this.framePcm(frame);
+        if (!bytes) {
+            return;
+        }
+        switch (track) {
+            case 'audio-out':
+                this.sdk.publishAudioFrame(bytes);
+                break;
+            case 'video-out':
+                if (this.features.VideoOut === true) {
+                    this.sdk.publishVideoFrame(bytes);
+                }
+                break;
+            case 'screen-out':
+                if (this.features.ScreenOut === true) {
+                    this.sdk.publishScreenFrame(bytes);
+                }
+                break;
+            default:
+                // An inbound track was passed to SendMedia — ignore (defensive).
+                break;
+        }
+    }
+    /**
+     * Registers the inbound-media handler. The driver forwards each raw per-participant audio frame
+     * (with its speaker identity) to this handler; the engine routes it to `IRealtimeSession.SendInput`.
+     *
+     * @param handler Invoked with each inbound media frame.
+     */
+    OnMedia(handler) {
+        this.mediaHandler = handler;
+    }
+    // ── Capability-gated virtuals LiveKit supports (gated by SupportedFeatures) ───────
+    /**
+     * Returns the current LiveKit participant roster (gated by `SpeakerDiarization`). Re-asserts the
+     * flag (defense-in-depth) so even an engine-bypassing caller cannot pull a roster a disabled
+     * provider forbids.
+     *
+     * @returns The current participants.
+     * @throws {BridgeCapabilityNotSupportedError} when diarization is not enabled for the provider.
+     */
+    async GetParticipants() {
+        this.RequireFeature('SpeakerDiarization');
+        if (!this.sdk) {
+            return [];
+        }
+        const participants = await this.sdk.getParticipants();
+        return participants.map(toBridgeParticipant);
+    }
+    /**
+     * Registers a roster-change handler (gated by `SpeakerDiarization`). The driver fires it from the
+     * SDK's participant join/leave stream with the full current roster.
+     *
+     * @param handler Invoked with the updated participant list on each change.
+     * @throws {BridgeCapabilityNotSupportedError} when diarization is not enabled.
+     */
+    OnParticipantChange(handler) {
+        this.RequireFeature('SpeakerDiarization');
+        this.participantHandler = handler;
+    }
+    /**
+     * Returns the LiveKit Meeting Controls event source for this session (roster · speaking · mute), or
+     * `null` when diarization is off (no roster to facilitate). The engine wires the Meeting Controls
+     * channel from this.
+     */
+    GetMeetingControlsEventSource() {
+        return this.meetingControls;
+    }
+    // ── LiveKit-native surfaces (used by the channel plane / turn-taking) ────────────
+    /**
+     * Sends a message on the LiveKit data channel — the room-native "chat". Exposed for the channel
+     * plane / turn-taking hybrid mode (the social-cost-free "raise hand"). Best-effort — a failure is
+     * logged, never fatal.
+     *
+     * @param text The data/chat message to send.
+     */
+    async SendDataMessage(text) {
+        if (!this.sdk) {
+            return;
+        }
+        try {
+            await this.sdk.sendDataMessage(text);
+        }
+        catch (err) {
+            LogError(`[LiveKitBridge] sendDataMessage failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** The bot's participant identity in the joined room (or `null` before {@link Connect}). */
+    get BotIdentity() {
+        return this.botIdentity;
+    }
+    // ── internals ────────────────────────────────────────────────────────────────────
+    /**
+     * Wires the SDK's inbound per-participant audio callback to a diarized inbound
+     * {@link BridgeMediaFrame}. The SFU never echoes the bot's own audio, so no self-audio gate is
+     * needed; the frame's `SpeakerLabel` is the source participant identity.
+     */
+    wireInboundAudio(sdk) {
+        sdk.onAudioTrack((frame) => {
+            // Mark the speaking participant on the Meeting Controls source for who's-speaking perception.
+            this.meetingControls?.NotifySpeaking([frame.ParticipantIdentity]);
+            this.mediaHandler?.({
+                Track: 'audio-in',
+                Bytes: frame.Pcm,
+                SpeakerLabel: frame.ParticipantIdentity,
+                TimestampMs: frame.TimestampMs ?? Date.now(),
+            });
+        });
+    }
+    /**
+     * Wires the SDK's participant join/leave streams ONCE (the driver is the single owner; the SDK seam
+     * is latest-handler-wins). Each roster change fans out to both the driver's own roster-change
+     * handler and the Meeting Controls source.
+     */
+    wireRoster(sdk) {
+        sdk.onParticipantJoin(() => void this.refreshRoster(sdk));
+        sdk.onParticipantLeave(() => void this.refreshRoster(sdk));
+    }
+    /** Pulls the current roster from the SDK and fans it out to both the participant handler + Meeting Controls. */
+    async refreshRoster(sdk) {
+        try {
+            const participants = await sdk.getParticipants();
+            this.participantHandler?.(participants.map(toBridgeParticipant));
+            this.meetingControls?.IngestRoster(participants);
+        }
+        catch (err) {
+            LogError(`[LiveKitBridge] roster refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** Handles the SDK's room-disconnected signal: surface an empty roster so the engine sees everyone gone. */
+    handleRoomDisconnected() {
+        this.participantHandler?.([]);
+        this.meetingControls?.IngestRoster([]);
+    }
+    /** Builds the SDK connect args from the bridge context (Address is the room URL; token from config). */
+    buildConnectArgs(ctx) {
+        const config = ctx.Configuration ?? {};
+        return {
+            RoomUrl: ctx.Address,
+            AccessToken: typeof config.AccessToken === 'string' ? config.AccessToken : '',
+            BotDisplayName: typeof config.BotDisplayName === 'string' ? config.BotDisplayName : `${ctx.ProviderName} Agent`,
+        };
+    }
+    /** Returns the bytes of an outbound media frame, preferring the binary payload. */
+    framePcm(frame) {
+        if (frame.Bytes) {
+            return frame.Bytes;
+        }
+        if (frame.Base64) {
+            return this.decodeBase64(frame.Base64);
+        }
+        return undefined;
+    }
+    /** Decodes a base64 payload to an `ArrayBuffer` (Node `Buffer` fast path, `atob` fallback). */
+    decodeBase64(base64) {
+        if (typeof Buffer !== 'undefined') {
+            const buf = Buffer.from(base64, 'base64');
+            const out = new Uint8Array(buf.byteLength);
+            out.set(buf);
+            return out.buffer;
+        }
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes.buffer;
+    }
+};
+LiveKitBridge = __decorate([
+    RegisterClass(BaseRealtimeBridge, LIVEKIT_BRIDGE_DRIVER_CLASS)
+], LiveKitBridge);
+export { LiveKitBridge };
+/**
+ * Tree-shaking-prevention loader. Modern bundlers cannot see the `@RegisterClass` dynamic registration
+ * of {@link LiveKitBridge} and may eliminate it. Import and call this no-op from a static code path
+ * (the package entry point does) so the `ClassFactory` can resolve `'LiveKitBridge'`.
+ */
+export function LoadLiveKitBridge() {
+    // Intentionally empty — referencing the module is what prevents tree-shaking.
+}
+//# sourceMappingURL=livekit-bridge.js.map

package/dist/livekit-bridge.js.map

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

package/dist/livekit-meeting-controls.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Adapts the {@link ILiveKitRoomSdk} participant / speaking stream into an
+ * {@link IBridgeMeetingControlsEventSource} so the bridge engine can wire the **Meeting Controls**
+ * facilitator channel (roster · who's-speaking · hand-raise queue) for a LiveKit room session. This is
+ * the §4b "the bridge contributes a channel" pattern realized for the MJ-native room — no channel logic
+ * lives here, only the platform→channel signal mapping.
+ *
+ * ## What LiveKit contributes (vs. Zoom)
+ * - **Roster + speaking**: native (per-participant tracks → diarization → speaking attribution).
+ * - **Hand-raise**: LiveKit has **no built-in raise-hand**. The channel still offers the facilitator
+ *   hand-raise *queue* (an MJ construct), but no PLATFORM hand-raise signal arrives, so
+ *   {@link IngestHandRaise} is available for an app that layers raise-hand over data messages — it is
+ *   simply never fired by the room itself.
+ * - **Mute**: LiveKit room-admin can mute a participant's published track, so the `Mute` capability is
+ *   advertised and {@link MuteParticipant} actuates it through the SDK adapter.
+ */
+import { IBridgeMeetingControlsEventSource, BridgeMeetingParticipant, BridgeMeetingControlsCapability } from '@memberjunction/ai-bridge-base';
+import { ILiveKitRoomSdk, LiveKitParticipant } from './livekit-sdk.js';
+/** Maps one LiveKit participant onto the channel's {@link BridgeMeetingParticipant} shape. */
+export declare function toMeetingParticipant(p: LiveKitParticipant): BridgeMeetingParticipant;
+/**
+ * LiveKit's adapter to the Meeting Controls channel's event source. It maintains a live roster and
+ * mirrors diarized speaking signals, and actuates mute through the SDK adapter.
+ *
+ * **The driver owns the SDK subscriptions** (the SDK seam is "latest handler wins") and **feeds this
+ * source imperatively** via {@link IngestRoster} / {@link IngestSpeaking} / {@link IngestHandRaise}.
+ * This source only needs the SDK for the one *action* it actuates — {@link MuteParticipant}. The
+ * Meeting Controls channel subscribes the three `On*` streams in turn.
+ *
+ * The driver constructs ONE of these per session (only when the provider has `SpeakerDiarization`, i.e.
+ * there is a roster to facilitate) and returns it from `LiveKitBridge.GetMeetingControlsEventSource`.
+ */
+export declare class LiveKitMeetingControlsEventSource implements IBridgeMeetingControlsEventSource {
+    private readonly sdk;
+    /** Live roster keyed by participant identity (lowercased), kept current by {@link IngestRoster}. */
+    private readonly roster;
+    private rosterHandler?;
+    private speakingHandler?;
+    private handRaiseHandler?;
+    /** LiveKit room-admin can mute a published track, so the facilitator `MuteParticipant` tool is offered. */
+    readonly Capabilities: ReadonlyArray<BridgeMeetingControlsCapability>;
+    /**
+     * @param sdk The LiveKit SDK seam used only to actuate {@link MuteParticipant} — all *perception* is
+     *   fed in by the driver via the `Ingest*` methods so the SDK keeps a single subscriber per event.
+     */
+    constructor(sdk: ILiveKitRoomSdk);
+    /**
+     * Replaces the roster with a fresh snapshot from the driver and emits it to the channel. Called by
+     * the driver after the initial connect and on every participant join/leave.
+     *
+     * @param participants The full current LiveKit roster.
+     */
+    IngestRoster(participants: LiveKitParticipant[]): void;
+    /**
+     * Forwards a hand-raise/lower signal to the channel. LiveKit emits none natively; this exists for an
+     * app that layers raise-hand over data messages.
+     *
+     * @param participantId The participant whose hand changed.
+     * @param raised Whether the hand is now raised.
+     */
+    IngestHandRaise(participantId: string, raised: boolean): void;
+    /**
+     * Forwards a diarized speaking-set change from the driver to the channel.
+     *
+     * @param participantIds The identities currently speaking.
+     */
+    IngestSpeaking(participantIds: string[]): void;
+    /**
+     * Convenience alias for {@link IngestSpeaking}, kept because "notify" reads naturally at the
+     * driver's inbound-audio call site.
+     *
+     * @param participantIds The identities currently speaking.
+     */
+    NotifySpeaking(participantIds: string[]): void;
+    /** @inheritdoc */
+    OnRosterChange(handler: (participants: BridgeMeetingParticipant[]) => void): void;
+    /** @inheritdoc */
+    OnSpeakingChange(handler: (participantIds: string[]) => void): void;
+    /** @inheritdoc */
+    OnHandRaiseChange(handler: (participantId: string, raised: boolean) => void): void;
+    /** @inheritdoc */
+    MuteParticipant(participantId: string): Promise<void>;
+    /** Actuates a mute through the SDK adapter's data-channel admin path. */
+    private muteViaSdk;
+    private emitRoster;
+    private key;
+}
+//# sourceMappingURL=livekit-meeting-controls.d.ts.map

package/dist/livekit-meeting-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit-meeting-controls.d.ts","sourceRoot":"","sources":["../src/livekit-meeting-controls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACH,iCAAiC,EACjC,wBAAwB,EACxB,+BAA+B,EAElC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAA0B,MAAM,eAAe,CAAC;AAoB5F,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,kBAAkB,GAAG,wBAAwB,CAOpF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iCAAkC,YAAW,iCAAiC;IAe3E,OAAO,CAAC,QAAQ,CAAC,GAAG;IAdhC,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+C;IAEtE,OAAO,CAAC,aAAa,CAAC,CAAqD;IAC3E,OAAO,CAAC,eAAe,CAAC,CAAqC;IAC7D,OAAO,CAAC,gBAAgB,CAAC,CAAmD;IAE5E,2GAA2G;IAC3G,SAAgB,YAAY,EAAE,aAAa,CAAC,+BAA+B,CAAC,CAAY;IAExF;;;OAGG;gBAC0B,GAAG,EAAE,eAAe;IAIjD;;;;;OAKG;IACI,YAAY,CAAC,YAAY,EAAE,kBAAkB,EAAE,GAAG,IAAI;IAQ7D;;;;;;OAMG;IACI,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAIpE;;;;OAIG;IACI,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI;IAIrD;;;;;OAKG;IACI,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI;IAMrD,kBAAkB;IACX,cAAc,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,wBAAwB,EAAE,KAAK,IAAI,GAAG,IAAI;IAMxF,kBAAkB;IACX,gBAAgB,CAAC,OAAO,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,IAAI;IAI1E,kBAAkB;IACX,iBAAiB,CAAC,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAIzF,kBAAkB;IACL,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlE,yEAAyE;YAC3D,UAAU;IAMxB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,GAAG;CAGd"}

package/dist/livekit-meeting-controls.js

@@ -0,0 +1,143 @@
+/**
+ * Adapts the {@link ILiveKitRoomSdk} participant / speaking stream into an
+ * {@link IBridgeMeetingControlsEventSource} so the bridge engine can wire the **Meeting Controls**
+ * facilitator channel (roster · who's-speaking · hand-raise queue) for a LiveKit room session. This is
+ * the §4b "the bridge contributes a channel" pattern realized for the MJ-native room — no channel logic
+ * lives here, only the platform→channel signal mapping.
+ *
+ * ## What LiveKit contributes (vs. Zoom)
+ * - **Roster + speaking**: native (per-participant tracks → diarization → speaking attribution).
+ * - **Hand-raise**: LiveKit has **no built-in raise-hand**. The channel still offers the facilitator
+ *   hand-raise *queue* (an MJ construct), but no PLATFORM hand-raise signal arrives, so
+ *   {@link IngestHandRaise} is available for an app that layers raise-hand over data messages — it is
+ *   simply never fired by the room itself.
+ * - **Mute**: LiveKit room-admin can mute a participant's published track, so the `Mute` capability is
+ *   advertised and {@link MuteParticipant} actuates it through the SDK adapter.
+ */
+/**
+ * Maps a LiveKit participant role to the bridge's meeting-participant role. LiveKit has no distinct
+ * "Agent" role; the bot is flagged via `IsLocal` and surfaced as `'Agent'`.
+ */
+function mapRole(role, isLocal) {
+    if (isLocal) {
+        return 'Agent';
+    }
+    switch (role) {
+        case 'Host':
+            return 'Host';
+        case 'CoHost':
+            return 'CoHost';
+        default:
+            return 'Participant';
+    }
+}
+/** Maps one LiveKit participant onto the channel's {@link BridgeMeetingParticipant} shape. */
+export function toMeetingParticipant(p) {
+    return {
+        ParticipantId: p.Identity,
+        DisplayName: p.DisplayName,
+        Role: mapRole(p.Role, p.IsLocal),
+        IsAgent: p.IsLocal === true,
+    };
+}
+/**
+ * LiveKit's adapter to the Meeting Controls channel's event source. It maintains a live roster and
+ * mirrors diarized speaking signals, and actuates mute through the SDK adapter.
+ *
+ * **The driver owns the SDK subscriptions** (the SDK seam is "latest handler wins") and **feeds this
+ * source imperatively** via {@link IngestRoster} / {@link IngestSpeaking} / {@link IngestHandRaise}.
+ * This source only needs the SDK for the one *action* it actuates — {@link MuteParticipant}. The
+ * Meeting Controls channel subscribes the three `On*` streams in turn.
+ *
+ * The driver constructs ONE of these per session (only when the provider has `SpeakerDiarization`, i.e.
+ * there is a roster to facilitate) and returns it from `LiveKitBridge.GetMeetingControlsEventSource`.
+ */
+export class LiveKitMeetingControlsEventSource {
+    /**
+     * @param sdk The LiveKit SDK seam used only to actuate {@link MuteParticipant} — all *perception* is
+     *   fed in by the driver via the `Ingest*` methods so the SDK keeps a single subscriber per event.
+     */
+    constructor(sdk) {
+        this.sdk = sdk;
+        /** Live roster keyed by participant identity (lowercased), kept current by {@link IngestRoster}. */
+        this.roster = new Map();
+        /** LiveKit room-admin can mute a published track, so the facilitator `MuteParticipant` tool is offered. */
+        this.Capabilities = ['Mute'];
+    }
+    // ── Driver-fed perception (the driver owns the SDK subscriptions) ─────────────────
+    /**
+     * Replaces the roster with a fresh snapshot from the driver and emits it to the channel. Called by
+     * the driver after the initial connect and on every participant join/leave.
+     *
+     * @param participants The full current LiveKit roster.
+     */
+    IngestRoster(participants) {
+        this.roster.clear();
+        for (const p of participants) {
+            this.roster.set(this.key(p.Identity), toMeetingParticipant(p));
+        }
+        this.emitRoster();
+    }
+    /**
+     * Forwards a hand-raise/lower signal to the channel. LiveKit emits none natively; this exists for an
+     * app that layers raise-hand over data messages.
+     *
+     * @param participantId The participant whose hand changed.
+     * @param raised Whether the hand is now raised.
+     */
+    IngestHandRaise(participantId, raised) {
+        this.handRaiseHandler?.(participantId, raised);
+    }
+    /**
+     * Forwards a diarized speaking-set change from the driver to the channel.
+     *
+     * @param participantIds The identities currently speaking.
+     */
+    IngestSpeaking(participantIds) {
+        this.speakingHandler?.(participantIds);
+    }
+    /**
+     * Convenience alias for {@link IngestSpeaking}, kept because "notify" reads naturally at the
+     * driver's inbound-audio call site.
+     *
+     * @param participantIds The identities currently speaking.
+     */
+    NotifySpeaking(participantIds) {
+        this.IngestSpeaking(participantIds);
+    }
+    // ── IBridgeMeetingControlsEventSource ────────────────────────────────────────────
+    /** @inheritdoc */
+    OnRosterChange(handler) {
+        this.rosterHandler = handler;
+        // Emit the current roster immediately so a late subscriber is not blank.
+        this.emitRoster();
+    }
+    /** @inheritdoc */
+    OnSpeakingChange(handler) {
+        this.speakingHandler = handler;
+    }
+    /** @inheritdoc */
+    OnHandRaiseChange(handler) {
+        this.handRaiseHandler = handler;
+    }
+    /** @inheritdoc */
+    async MuteParticipant(participantId) {
+        // LiveKit mute is actuated by the room-admin path; the SDK adapter maps this onto its
+        // mute-published-track call. The fake captures it for tests.
+        await this.muteViaSdk(participantId);
+    }
+    // ── internals ────────────────────────────────────────────────────────────────────
+    /** Actuates a mute through the SDK adapter's data-channel admin path. */
+    async muteViaSdk(participantId) {
+        // The SDK seam does not surface a dedicated mute primitive (room-admin mute is a server-SDK
+        // concern bound at deployment); we signal it as a structured data message the adapter recognizes.
+        await this.sdk.sendDataMessage(`__mj_mute:${participantId}`);
+    }
+    emitRoster() {
+        this.rosterHandler?.(Array.from(this.roster.values()));
+    }
+    key(identity) {
+        return identity.trim().toLowerCase();
+    }
+}
+//# sourceMappingURL=livekit-meeting-controls.js.map

package/dist/livekit-meeting-controls.js.map

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

package/dist/livekit-sdk.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The injectable **LiveKit room SDK seam** — the minimal set of operations
+ * {@link import('./livekit-bridge.js').LiveKitBridge} needs from LiveKit, declared as an interface so the
+ * driver builds and unit-tests against an in-memory fake with **no network and no real LiveKit SDK**.
+ *
+ * ## LiveKit is the MJ-NATIVE room (self-hosted), not a 3rd-party platform
+ * Every OTHER bridge in this program connects **out** to a meeting hosted by someone else (Zoom,
+ * Teams, Meet, Webex, Slack, Discord) or to a telephony carrier (Twilio, Vonage, RingCentral). LiveKit
+ * is the opposite: it is an **open-source WebRTC SFU that MJ runs itself** — the "MJ-native room"
+ * (`/plans/realtime/realtime-bridges-architecture.md` §4c). The architecture deliberately treats a Zoom
+ * meeting, a Teams meeting, and an MJ-native LiveKit room **identically** — all are multi-party media
+ * transports — so LiveKit is "*another bridge, not a special build*." The only practical differences:
+ * - **We own the room.** No marketplace review, no per-platform bot-admission quirks; MJ mints the
+ *   access token and the room exists because MJ stood up the SFU. An MJ-native multi-party experience
+ *   (e.g. embedded in Explorer) is just *this* bridge.
+ * - **`connect(roomUrl, token)`** takes a LiveKit room URL + a signed access token (minted upstream by
+ *   MJ's credential/token layer — never inline secrets), rather than a join URL we were handed.
+ *
+ * ## Production binding (TODO at deployment)
+ * In production this interface is bound to **`livekit-server-sdk`** (token minting / room admin) plus a
+ * **room client** (the Node WebRTC participant — e.g. `@livekit/rtc-node`) so the bot can publish/
+ * subscribe media. The named operations map to the SDK as follows:
+ * - {@link connect} / {@link disconnect} → the room client `connect()` / `disconnect()` lifecycle.
+ * - {@link publishAudioFrame} → publishing PCM on the bot's audio track (the agent's voice).
+ * - {@link onAudioTrack} → subscribing each remote participant's audio track; LiveKit delivers tracks
+ *   **per participant**, which is the native source of speaker labels for diarization (no extra mixer).
+ * - {@link publishVideoFrame} / {@link publishScreenFrame} → publishing the bot's camera / screen-share
+ *   tracks (LiveKit does full A/V/screen; the realtime models light audio first).
+ * - {@link onParticipantJoin} / {@link onParticipantLeave} / {@link getParticipants} → the room's
+ *   `ParticipantConnected` / `ParticipantDisconnected` events + the participant list.
+ * - {@link sendDataMessage} → the LiveKit **data channel** (reliable data publish) — used for chat.
+ * - {@link onDisconnected} → the room `Disconnected` event (the SFU closed / the bot was removed).
+ *
+ * ## Echo / self-audio
+ * A LiveKit SFU **never delivers a participant its own published track back** — the bot does not hear
+ * its own voice, so no echo gate is needed here (documented in {@link onAudioTrack}). The bridge still
+ * flags its own track via {@link LiveKitParticipant.IsLocal} defensively.
+ *
+ * Binding the real SDK is a thin adapter that implements this interface; the driver and its tests do
+ * not change. **None of the SDK types leak into this package.**
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §4c and `/guides/REALTIME_BRIDGES_GUIDE.md`.
+ */
+/** The role a LiveKit participant holds, normalized to the bridge's participant roles. */
+export type LiveKitParticipantRole = 'Host' | 'CoHost' | 'Participant';
+/**
+ * One LiveKit room participant as the seam reports it. Platform-native and minimal — the driver maps
+ * this onto `BridgeParticipantInfo` / `BridgeMeetingParticipant`.
+ */
+export interface LiveKitParticipant {
+    /** The LiveKit participant identity (stable, application-assigned — the SID's human-facing key). */
+    Identity: string;
+    /** The participant's display name as LiveKit reports it (the `name` attribute), when set. */
+    DisplayName?: string;
+    /** The participant's room role (derived from participant metadata / permissions by the adapter). */
+    Role: LiveKitParticipantRole;
+    /** Whether this participant is the bridge's own bot (LiveKit's local participant). */
+    IsLocal?: boolean;
+}
+/**
+ * One frame of raw per-participant audio the seam surfaces for diarization + the agent's "hearing".
+ * Because LiveKit subscribes tracks **per participant**, every inbound frame is already attributed to a
+ * single speaker — diarization comes free from the SFU.
+ */
+export interface LiveKitAudioFrame {
+    /** Raw PCM audio bytes for this frame. */
+    Pcm: ArrayBuffer;
+    /** The LiveKit participant identity this audio came from (the diarization speaker label). */
+    ParticipantIdentity: string;
+    /** The participant's display name at capture time, when known. */
+    DisplayName?: string;
+    /** Optional epoch-ms capture timestamp. */
+    TimestampMs?: number;
+}
+/** Arguments to {@link ILiveKitRoomSdk.connect} — what the bot needs to join an MJ-native room. */
+export interface LiveKitConnectArgs {
+    /** The LiveKit room server URL (e.g. `wss://livekit.myorg.com`). MJ-owned, self-hosted. */
+    RoomUrl: string;
+    /**
+     * The signed LiveKit access token authorizing the bot to join a specific room as a participant.
+     * Minted upstream by MJ's token/credential layer (it encodes the room name + grants). Never inline
+     * secrets — this arrives already-signed.
+     */
+    AccessToken: string;
+    /** The display name the bot appears as in the participant list. */
+    BotDisplayName: string;
+}
+/** The handles the seam returns after a successful {@link ILiveKitRoomSdk.connect}. */
+export interface LiveKitConnectResult {
+    /** The bot's own participant identity in the joined room. */
+    BotIdentity: string;
+    /** The LiveKit room name the bot joined (the durable external connection id). */
+    RoomName: string;
+}
+/**
+ * The minimal LiveKit room SDK surface the {@link import('./livekit-bridge.js').LiveKitBridge} depends on.
+ * Production binds this to `livekit-server-sdk` + a room client; tests inject a `FakeLiveKitRoomSdk`.
+ */
+export interface ILiveKitRoomSdk {
+    /**
+     * Connects to the MJ-native LiveKit room as a bot participant and brings the bot online. Returns
+     * the bot's identity + the room name.
+     *
+     * @param args Connect parameters (room URL, signed access token, bot name).
+     * @returns The bot identity + room handles.
+     */
+    connect(args: LiveKitConnectArgs): Promise<LiveKitConnectResult>;
+    /** Disconnects from the room and releases SDK resources. */
+    disconnect(): Promise<void>;
+    /**
+     * Publishes one raw PCM audio frame on the bot's audio track (the agent's voice into the room).
+     *
+     * @param pcm The PCM audio bytes to publish.
+     */
+    publishAudioFrame(pcm: ArrayBuffer): void;
+    /**
+     * Subscribes inbound per-participant audio frames (what the agent hears, carrying the speaker
+     * identity for diarization). "Latest handler wins." The SFU never echoes the bot's own published
+     * audio back, so frames here are always from OTHER participants.
+     *
+     * @param cb Invoked with each inbound, per-participant audio frame.
+     */
+    onAudioTrack(cb: (frame: LiveKitAudioFrame) => void): void;
+    /**
+     * Publishes one raw video frame on the bot's camera track. LiveKit does full video; the realtime
+     * models light audio first, so this is wired but typically unused until a model emits video.
+     *
+     * @param frame The encoded/raw video frame bytes to publish.
+     */
+    publishVideoFrame(frame: ArrayBuffer): void;
+    /**
+     * Publishes one raw screen-share frame on the bot's screen track (e.g. a Remote Browser channel's
+     * viewport). LiveKit does full screen share.
+     *
+     * @param frame The encoded/raw screen frame bytes to publish.
+     */
+    publishScreenFrame(frame: ArrayBuffer): void;
+    /**
+     * Registers a callback fired when a participant connects. "Latest handler wins."
+     *
+     * @param cb Invoked with the participant who joined.
+     */
+    onParticipantJoin(cb: (participant: LiveKitParticipant) => void): void;
+    /**
+     * Registers a callback fired when a participant disconnects. "Latest handler wins."
+     *
+     * @param cb Invoked with the participant identity that left.
+     */
+    onParticipantLeave(cb: (participantIdentity: string) => void): void;
+    /**
+     * Returns the current participant list (including the bot).
+     *
+     * @returns The current participants.
+     */
+    getParticipants(): Promise<LiveKitParticipant[]>;
+    /**
+     * Sends a text message on the LiveKit data channel (reliable publish to all participants) — the
+     * room-native "chat".
+     *
+     * @param text The chat/data message text.
+     */
+    sendDataMessage(text: string): Promise<void>;
+    /**
+     * Registers a callback fired when the room disconnects the bot (SFU closed / bot removed). "Latest
+     * handler wins."
+     *
+     * @param cb Invoked when the room has disconnected.
+     */
+    onDisconnected(cb: () => void): void;
+}
+/**
+ * A factory that constructs an {@link ILiveKitRoomSdk} for a session — the creation seam (mirroring
+ * Zoom's `ZoomMeetingSdkFactory`). Production supplies a factory that builds the real LiveKit adapter
+ * (`livekit-server-sdk` + a room client) from resolved config; tests supply one that returns a
+ * `FakeLiveKitRoomSdk`.
+ *
+ * @param config The resolved provider/session configuration (room URL, region, credential refs already
+ *   resolved upstream into a signed token).
+ * @returns The LiveKit room SDK instance to drive the room with.
+ */
+export type LiveKitRoomSdkFactory = (config?: Record<string, unknown>) => ILiveKitRoomSdk;
+//# sourceMappingURL=livekit-sdk.d.ts.map

package/dist/livekit-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit-sdk.d.ts","sourceRoot":"","sources":["../src/livekit-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,0FAA0F;AAC1F,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEvE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,oGAAoG;IACpG,QAAQ,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,IAAI,EAAE,sBAAsB,CAAC;IAC7B,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,0CAA0C;IAC1C,GAAG,EAAE,WAAW,CAAC;IACjB,6FAA6F;IAC7F,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IAC/B,2FAA2F;IAC3F,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACjC,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjE,4DAA4D;IAC5D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;OAIG;IACH,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAE1C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI,CAAC;IAE3D;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAE5C;;;;;OAKG;IACH,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAE7C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,EAAE,CAAC,WAAW,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI,CAAC;IAEvE;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAEpE;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,CAAC"}

package/dist/livekit-sdk.js

@@ -0,0 +1,45 @@
+/**
+ * The injectable **LiveKit room SDK seam** — the minimal set of operations
+ * {@link import('./livekit-bridge.js').LiveKitBridge} needs from LiveKit, declared as an interface so the
+ * driver builds and unit-tests against an in-memory fake with **no network and no real LiveKit SDK**.
+ *
+ * ## LiveKit is the MJ-NATIVE room (self-hosted), not a 3rd-party platform
+ * Every OTHER bridge in this program connects **out** to a meeting hosted by someone else (Zoom,
+ * Teams, Meet, Webex, Slack, Discord) or to a telephony carrier (Twilio, Vonage, RingCentral). LiveKit
+ * is the opposite: it is an **open-source WebRTC SFU that MJ runs itself** — the "MJ-native room"
+ * (`/plans/realtime/realtime-bridges-architecture.md` §4c). The architecture deliberately treats a Zoom
+ * meeting, a Teams meeting, and an MJ-native LiveKit room **identically** — all are multi-party media
+ * transports — so LiveKit is "*another bridge, not a special build*." The only practical differences:
+ * - **We own the room.** No marketplace review, no per-platform bot-admission quirks; MJ mints the
+ *   access token and the room exists because MJ stood up the SFU. An MJ-native multi-party experience
+ *   (e.g. embedded in Explorer) is just *this* bridge.
+ * - **`connect(roomUrl, token)`** takes a LiveKit room URL + a signed access token (minted upstream by
+ *   MJ's credential/token layer — never inline secrets), rather than a join URL we were handed.
+ *
+ * ## Production binding (TODO at deployment)
+ * In production this interface is bound to **`livekit-server-sdk`** (token minting / room admin) plus a
+ * **room client** (the Node WebRTC participant — e.g. `@livekit/rtc-node`) so the bot can publish/
+ * subscribe media. The named operations map to the SDK as follows:
+ * - {@link connect} / {@link disconnect} → the room client `connect()` / `disconnect()` lifecycle.
+ * - {@link publishAudioFrame} → publishing PCM on the bot's audio track (the agent's voice).
+ * - {@link onAudioTrack} → subscribing each remote participant's audio track; LiveKit delivers tracks
+ *   **per participant**, which is the native source of speaker labels for diarization (no extra mixer).
+ * - {@link publishVideoFrame} / {@link publishScreenFrame} → publishing the bot's camera / screen-share
+ *   tracks (LiveKit does full A/V/screen; the realtime models light audio first).
+ * - {@link onParticipantJoin} / {@link onParticipantLeave} / {@link getParticipants} → the room's
+ *   `ParticipantConnected` / `ParticipantDisconnected` events + the participant list.
+ * - {@link sendDataMessage} → the LiveKit **data channel** (reliable data publish) — used for chat.
+ * - {@link onDisconnected} → the room `Disconnected` event (the SFU closed / the bot was removed).
+ *
+ * ## Echo / self-audio
+ * A LiveKit SFU **never delivers a participant its own published track back** — the bot does not hear
+ * its own voice, so no echo gate is needed here (documented in {@link onAudioTrack}). The bridge still
+ * flags its own track via {@link LiveKitParticipant.IsLocal} defensively.
+ *
+ * Binding the real SDK is a thin adapter that implements this interface; the driver and its tests do
+ * not change. **None of the SDK types leak into this package.**
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §4c and `/guides/REALTIME_BRIDGES_GUIDE.md`.
+ */
+export {};
+//# sourceMappingURL=livekit-sdk.js.map

package/dist/livekit-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit-sdk.js","sourceRoot":"","sources":["../src/livekit-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG"}

package/package.json

@@ -1,10 +1,35 @@
 {
   "name": "@memberjunction/ai-bridge-livekit",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/ai-bridge-livekit",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.41.0",
+  "description": "MemberJunction: LiveKit Realtime Bridge driver — the MJ-native multi-party room. Unlike the other bridges (which connect OUT to a 3rd-party meeting platform), LiveKit is a SELF-HOSTED WebRTC SFU that MJ runs itself. Connects the realtime agent engine to a LiveKit room as a bot participant (audio/video/screen in+out, per-participant diarization, data-channel chat) via an injectable LiveKit room SDK seam, and contributes a Meeting Controls facilitator channel.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "start": "ts-node-dev src/index.ts",
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/core": "5.41.0",
+    "@memberjunction/global": "5.41.0",
+    "@memberjunction/core-entities": "5.41.0",
+    "@memberjunction/ai-bridge-base": "5.41.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.11",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }