@memberjunction/livekit-room-server 0.0.1 → 5.42.0

package/README.md

@@ -1,45 +1,92 @@
 # @memberjunction/livekit-room-server
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Server-side LiveKit support for MemberJunction: scoped **access-token minting**, the **agent-room
+session-start coordinator**, and **recording (egress)** control. This is the seam between the MJ realtime
+bridge and the browser LiveKit UI.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+```
+browser  ── GraphQL ──►  RealtimeBridgeResolver (MJServer)
+                                   │
+                                   ▼
+        @memberjunction/livekit-room-server   ← you are here
+        ├─ LiveKitTokenService          mint client + bot tokens (livekit-server-sdk)
+        ├─ LiveKitAgentRoomCoordinator  open realtime session → AIBridgeEngine.StartBridgeSession
+        └─ LiveKitEgressService         start/stop room recording
+```
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Why it exists
 
-## Purpose
+The realtime bridge already joins the **agent bot** to a LiveKit room with an MJ-minted token. Two gaps
+remained: (1) a **human** browser participant needs its own scoped token for the same room, and (2) nothing
+outside the bridge package opened a realtime session and called `StartBridgeSession`. This package closes
+both.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/livekit-room-server`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Configuration
 
-## What is OIDC Trusted Publishing?
+Credentials resolve from explicit config or environment variables (never inline secrets):
 
-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.
+```bash
+LIVEKIT_URL=wss://livekit.myorg.com
+LIVEKIT_API_KEY=...
+LIVEKIT_API_SECRET=...
+```
 
-## Setup Instructions
+> **Where the LiveKit server comes from — see [`docker/livekit/README.md`](../../docker/livekit/README.md) (canonical setup guide):**
+> - **Local dev:** spin up a throwaway LiveKit server with matching dev creds — Docker (`docker compose up -d`) for
+>   browser-only testing, or native `livekit-server --config docker/livekit/livekit.yaml` for the agent-bot path on
+>   macOS. Then `LIVEKIT_URL=ws://localhost:7880` / `LIVEKIT_API_KEY=devkey` / `LIVEKIT_API_SECRET=mj-local-dev-livekit-secret-0123456789`.
+> - **Production / real-world:** use [**LiveKit Cloud**](https://cloud.livekit.io) — a hosted `wss://…livekit.cloud`
+>   URL + API key + secret to drop into `.env`, no server to run (or a properly-networked self-host).
 
-To properly configure OIDC trusted publishing for this package:
+## Token minting (fully functional)
 
-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
+```typescript
+import { LiveKitTokenService } from '@memberjunction/livekit-room-server';
 
-## DO NOT USE THIS PACKAGE
+const tokens = new LiveKitTokenService();              // reads env, or pass { ServerUrl, ApiKey, ApiSecret }
+const human = await tokens.MintClientToken('support-42', 'user-abc', 'Amith');
+// → { ServerUrl, Token, Identity, RoomName }  — hand Token to <mj-livekit-room>
+```
 
-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
+## Agent-room session-start harness
 
-## More Information
+`LiveKitAgentRoomCoordinator` is a `BaseSingleton`. It mints the bot token, opens the realtime model
+session via an injectable factory seam, and bridges it into the room:
 
-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)
+```typescript
+import { LiveKitAgentRoomCoordinator } from '@memberjunction/livekit-room-server';
 
----
+// At deployment/startup, bind the realtime-session factory (resolves a BaseRealtimeModel → IRealtimeSession):
+LiveKitAgentRoomCoordinator.Instance.SetSessionFactory(async (ctx) => openRealtimeSession(ctx));
 
-**Maintained for OIDC setup purposes only**
+// Then, per request:
+const session = await LiveKitAgentRoomCoordinator.Instance.StartAgentRoomSession({
+    AgentSessionID, RoomName: 'support-42', AgentName: 'Sage', TurnMode: 'Passive', ContextUser,
+});
+```
+
+The factory is a seam (like `LiveKitBridge.SetSdkFactory`) so this package carries no heavy agent-runtime
+coupling and unit-tests with a stub session. The actual native room media client (`@livekit/rtc-node`) is
+bound on the bridge driver at deployment, per the realtime-bridge buildout plan.
+
+## Recording (egress)
+
+```typescript
+import { LiveKitEgressService } from '@memberjunction/livekit-room-server';
+
+const egress = new LiveKitEgressService();
+const rec = await egress.StartRoomRecording({ RoomName: 'support-42' });   // → { EgressID, Status }
+await egress.StopRecording(rec.EgressID);
+```
+
+Egress output storage (S3 / GCS / Azure / LiveKit Cloud) is configured on the LiveKit project.
+
+## GraphQL surface
+
+These are exposed to the browser via MJServer's `RealtimeBridgeResolver`:
+`MintLiveKitClientToken`, `StartLiveKitAgentRoomSession`, `StartLiveKitRecording`, `StopLiveKitRecording`.
+Call them from the browser with `GraphQLLiveKitClient` in `@memberjunction/graphql-dataprovider`.
+
+## License
+
+ISC © MemberJunction.com

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Public entry point for `@memberjunction/livekit-room-server`.
+ *
+ * Server-side LiveKit room support for MemberJunction: scoped token minting + the agent-room session-start
+ * coordinator that bridges a realtime model session into a LiveKit room.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+export { LiveKitTokenService, type LiveKitServerConfig, type LiveKitTokenRole, type MintTokenParams, type MintedToken } from './livekit-token-service.js';
+export { LiveKitAgentRoomCoordinator, LIVEKIT_BRIDGE_DRIVER_CLASS, type BridgeOps, type RealtimeSessionFactory, type RealtimeSessionStartContext, type StartAgentRoomSessionParams, type AgentRoomSession, } from './livekit-agent-room-coordinator.js';
+export { LiveKitEgressService, wsToHttpUrl, type EgressClientLike, type StartRecordingParams, type RecordingInfo } from './livekit-egress-service.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;;;;;;;GAOG;AAWH,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEvJ,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,GACtB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Public entry point for `@memberjunction/livekit-room-server`.
+ *
+ * Server-side LiveKit room support for MemberJunction: scoped token minting + the agent-room session-start
+ * coordinator that bridges a realtime model session into a LiveKit room.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { LoadLiveKitBridge } from '@memberjunction/ai-bridge-livekit';
+// The coordinator's StartAgentRoomSession resolves the 'LiveKitBridge' driver via the engine's
+// ClassFactory, so its @RegisterClass registration MUST have run. Importing the driver package here —
+// the server-side LiveKit layer that DEPENDS on the driver — guarantees it: loading this package (which
+// MJServer does) registers the bridge. The no-op call is a tree-shake guard. Without this the room start
+// fails with "No bridge driver registered for DriverClass 'LiveKitBridge'".
+LoadLiveKitBridge();
+export { LiveKitTokenService } from './livekit-token-service.js';
+export { LiveKitAgentRoomCoordinator, LIVEKIT_BRIDGE_DRIVER_CLASS, } from './livekit-agent-room-coordinator.js';
+export { LiveKitEgressService, wsToHttpUrl } from './livekit-egress-service.js';
+//# 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;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE,+FAA+F;AAC/F,sGAAsG;AACtG,wGAAwG;AACxG,yGAAyG;AACzG,4EAA4E;AAC5E,iBAAiB,EAAE,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAA2F,MAAM,yBAAyB,CAAC;AAEvJ,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,GAM5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAwE,MAAM,0BAA0B,CAAC"}

package/dist/livekit-agent-room-coordinator.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview {@link LiveKitAgentRoomCoordinator} — the server-side **session-start harness** for the
+ * MJ-native LiveKit room (§1 of the realtime-bridge buildout plan). Given an agent + a room, it:
+ *   1. mints the agent bot's scoped LiveKit token ({@link LiveKitTokenService}),
+ *   2. opens the realtime model session via an injectable {@link RealtimeSessionFactory} seam, and
+ *   3. bridges that session into the room through {@link AIBridgeEngine.StartBridgeSession} (which wires
+ *      the transport seam + turn-taking automatically).
+ *
+ * The realtime-session factory is a seam (mirroring `LiveKitBridge.SetSdkFactory`): production binds it to
+ * the real model-resolution path (`@memberjunction/ai-agents`), and tests/de-risk inject a stub session.
+ * This keeps the coordinator free of heavy agent-runtime coupling while still owning the orchestration.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { BaseSingleton } from '@memberjunction/global';
+import { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import type { IRealtimeSession } from '@memberjunction/ai';
+import { type BridgeDisconnectReason, type BridgeTurnMode } from '@memberjunction/ai-bridge-base';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { LiveKitTokenService } from './livekit-token-service.js';
+/** The subset of {@link AIBridgeEngine} the coordinator drives — an injectable seam for unit testing. */
+export type BridgeOps = Pick<AIBridgeEngine, 'Config' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'StopBridgeSession'>;
+/** The `DriverClass` the LiveKit bridge registers under (must match the `MJ: AI Bridge Providers` row). */
+export declare const LIVEKIT_BRIDGE_DRIVER_CLASS = "LiveKitBridge";
+/** Context passed to the realtime-session factory when starting an agent room session. */
+export interface RealtimeSessionStartContext {
+    /** The agent to voice in the room, when known. */
+    AgentID?: string;
+    /** The agent's display name (used for the bot name + turn-taking matcher). */
+    AgentName?: string;
+    /** The TARGET agent the co-agent voices via `invoke-target-agent` (the one being "called"). */
+    TargetAgentID?: string;
+    /** Optional per-session Realtime MODEL override (Name or ID). */
+    RealtimeModelID?: string;
+    /** Optional per-session VOICE override (provider-native voice id). */
+    RealtimeVoice?: string;
+    /** The room being joined. */
+    RoomName: string;
+    /** The user the session runs as. */
+    ContextUser?: UserInfo;
+    /** The metadata provider for the session. */
+    MetadataProvider?: IMetadataProvider;
+    /** The MJ agent-session id — threaded into the co-agent observability run for session grouping. */
+    AgentSessionID?: string;
+    /**
+     * Multi-agent meeting mode — set when the agent joins a room that already has agents. Flows to the
+     * realtime session so its model's auto-response is disabled (speaks only when addressed).
+     */
+    MeetingMode?: boolean;
+    /** The names the agent answers to (display name + aliases) — phrasing for the meeting prompt. */
+    SelfNames?: string[];
+}
+/**
+ * Opens a realtime model session for the agent. Production binds this to the real model-resolution path;
+ * tests inject a stub. Defaults to a clear "not bound" error so misconfiguration fails loudly.
+ */
+export type RealtimeSessionFactory = (ctx: RealtimeSessionStartContext) => Promise<IRealtimeSession>;
+/** Parameters for {@link LiveKitAgentRoomCoordinator.StartAgentRoomSession}. */
+export interface StartAgentRoomSessionParams {
+    /** The MJ agent-session id this bridge belongs to. */
+    AgentSessionID: string;
+    /** The LiveKit room the agent should join. */
+    RoomName: string;
+    /** The agent to voice, when known. */
+    AgentID?: string;
+    /** The agent's display name (bot name + addressing). */
+    AgentName?: string;
+    /**
+     * The TARGET agent the co-agent voices (the one being "called"). Passed through to the realtime
+     * session factory so the Realtime Co-Agent has someone to delegate to via `invoke-target-agent`.
+     */
+    TargetAgentID?: string;
+    /** Optional per-session Realtime MODEL override (Name or ID) — wins over the co-agent config preference. */
+    RealtimeModelID?: string;
+    /** Optional per-session VOICE override (provider-native voice id) — gives this agent a distinct voice. */
+    RealtimeVoice?: string;
+    /** Extra aliases the agent answers to (for Passive turn-taking). */
+    AgentAliases?: string[];
+    /** Turn-taking mode. Default: `'Passive'` (speak only when addressed). */
+    TurnMode?: BridgeTurnMode;
+    /** The user the session runs as. */
+    ContextUser?: UserInfo;
+    /** The metadata provider for the session. */
+    MetadataProvider?: IMetadataProvider;
+}
+/** The result of starting an agent room session. */
+export interface AgentRoomSession {
+    /** The durable `MJ: AI Agent Session Bridges` row id. */
+    SessionBridgeID: string;
+    /** The room the agent joined. */
+    RoomName: string;
+    /** The LiveKit server URL. */
+    ServerUrl: string;
+}
+/**
+ * Coordinates starting (and stopping) an agent's presence in a LiveKit room. A process-wide singleton
+ * (per MJ convention) so deployment code can bind the realtime-session factory once at startup and the
+ * GraphQL resolver can use the same bound instance.
+ */
+export declare class LiveKitAgentRoomCoordinator extends BaseSingleton<LiveKitAgentRoomCoordinator> {
+    private tokenService;
+    /**
+     * Per-room roster of the agents currently bridged in (keyed by lowercased room name). Drives
+     * **multi-agent meeting detection**: when an agent joins a room that ALREADY holds an agent, the new
+     * agent starts in meeting mode (auto-response off + addressed-only) so several agents can share a room
+     * without all answering every utterance. The first agent stays a normal 1:1 voice (it isn't
+     * retroactively re-gated — that needs a live session re-config, a follow-up). See
+     * `plans/realtime/multi-agent-meeting-turn-taking.md`.
+     */
+    private roomRosters;
+    private bridgeOps;
+    private sessionFactory;
+    /** BaseSingleton requires a protected constructor. */
+    protected constructor();
+    /** The process-wide coordinator instance. */
+    static get Instance(): LiveKitAgentRoomCoordinator;
+    /**
+     * Binds the realtime-session factory (the model-session creation seam).
+     *
+     * @param factory The factory that opens an {@link IRealtimeSession} for an agent.
+     */
+    SetSessionFactory(factory: RealtimeSessionFactory): void;
+    /**
+     * Overrides the token service used to mint the bot token (e.g. to inject explicit credentials).
+     *
+     * @param service The token service to use.
+     */
+    SetTokenService(service: LiveKitTokenService): void;
+    /**
+     * Overrides the bridge operations used to resolve the provider + start/stop the bridge session (the
+     * injectable {@link AIBridgeEngine} seam — primarily for unit testing).
+     *
+     * @param ops The bridge operations to use.
+     */
+    SetBridgeOps(ops: BridgeOps): void;
+    /**
+     * Starts the agent's presence in a LiveKit room: mints the bot token, opens the realtime session, and
+     * bridges it into the room.
+     *
+     * @param params The session parameters.
+     * @returns The active session handles.
+     * @throws {Error} when the LiveKit provider is not configured/registered or the session factory is unbound.
+     */
+    StartAgentRoomSession(params: StartAgentRoomSessionParams): Promise<AgentRoomSession>;
+    /** Appends an agent to a room's roster (creating the room's list on first join). */
+    private addToRoster;
+    /** Removes an agent from whatever room roster holds its bridge id; prunes the room when it empties. */
+    private removeFromRoster;
+    /** The default native room-client wrapper specifier — the @livekit/rtc-node package this repo ships. */
+    private static readonly DEFAULT_NATIVE_MODULE;
+    /**
+     * Resolves the native LiveKit room-client module specifier for the bridge session. Prefers the
+     * `LIVEKIT_NATIVE_MODULE` env override (e.g. a deployment's custom-sample-rate wrapper), else the default
+     * {@link DEFAULT_NATIVE_MODULE}. Overridable in tests via {@link SetNativeModuleSpecifier}.
+     */
+    private resolveNativeModuleSpecifier;
+    /**
+     * Overrides the native room-client module specifier (primarily for unit testing — production resolves it
+     * from env / the default).
+     *
+     * @param specifier The module specifier to use, or `undefined` to clear the override.
+     */
+    SetNativeModuleSpecifier(specifier: string | undefined): void;
+    /** Test/deployment override for the native module specifier (see {@link resolveNativeModuleSpecifier}). */
+    private nativeModuleSpecifierOverride?;
+    /**
+     * Stops an agent room session (the bot leaves the room).
+     *
+     * @param sessionBridgeID The bridge row id returned from {@link StartAgentRoomSession}.
+     * @param reason Why the session is stopping. Default: `'Explicit'`.
+     * @param contextUser The acting user.
+     * @param provider The metadata provider.
+     */
+    StopAgentRoomSession(sessionBridgeID: string, reason?: BridgeDisconnectReason, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<boolean>;
+}
+//# sourceMappingURL=livekit-agent-room-coordinator.d.ts.map

package/dist/livekit-agent-room-coordinator.d.ts.map

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

package/dist/livekit-agent-room-coordinator.js

@@ -0,0 +1,218 @@
+/**
+ * @fileoverview {@link LiveKitAgentRoomCoordinator} — the server-side **session-start harness** for the
+ * MJ-native LiveKit room (§1 of the realtime-bridge buildout plan). Given an agent + a room, it:
+ *   1. mints the agent bot's scoped LiveKit token ({@link LiveKitTokenService}),
+ *   2. opens the realtime model session via an injectable {@link RealtimeSessionFactory} seam, and
+ *   3. bridges that session into the room through {@link AIBridgeEngine.StartBridgeSession} (which wires
+ *      the transport seam + turn-taking automatically).
+ *
+ * The realtime-session factory is a seam (mirroring `LiveKitBridge.SetSdkFactory`): production binds it to
+ * the real model-resolution path (`@memberjunction/ai-agents`), and tests/de-risk inject a stub session.
+ * This keeps the coordinator free of heavy agent-runtime coupling while still owning the orchestration.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { BaseSingleton } from '@memberjunction/global';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { AlwaysAddressedMatcher, RegexAddressedMatcher } from '@memberjunction/ai-bridge-base';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { LiveKitTokenService } from './livekit-token-service.js';
+/** The `DriverClass` the LiveKit bridge registers under (must match the `MJ: AI Bridge Providers` row). */
+export const LIVEKIT_BRIDGE_DRIVER_CLASS = 'LiveKitBridge';
+/**
+ * Coordinates starting (and stopping) an agent's presence in a LiveKit room. A process-wide singleton
+ * (per MJ convention) so deployment code can bind the realtime-session factory once at startup and the
+ * GraphQL resolver can use the same bound instance.
+ */
+export class LiveKitAgentRoomCoordinator extends BaseSingleton {
+    /** BaseSingleton requires a protected constructor. */
+    constructor() {
+        super();
+        this.tokenService = new LiveKitTokenService();
+        /**
+         * Per-room roster of the agents currently bridged in (keyed by lowercased room name). Drives
+         * **multi-agent meeting detection**: when an agent joins a room that ALREADY holds an agent, the new
+         * agent starts in meeting mode (auto-response off + addressed-only) so several agents can share a room
+         * without all answering every utterance. The first agent stays a normal 1:1 voice (it isn't
+         * retroactively re-gated — that needs a live session re-config, a follow-up). See
+         * `plans/realtime/multi-agent-meeting-turn-taking.md`.
+         */
+        this.roomRosters = new Map();
+        this.bridgeOps = AIBridgeEngine.Instance;
+        this.sessionFactory = () => {
+            throw new Error('LiveKitAgentRoomCoordinator has no realtime-session factory bound. Call SetSessionFactory(...) ' +
+                'with a factory that resolves a BaseRealtimeModel and returns an IRealtimeSession (see @memberjunction/ai-agents), ' +
+                'or inject a stub session in tests/de-risk runs.');
+        };
+    }
+    /** The process-wide coordinator instance. */
+    static get Instance() {
+        return super.getInstance();
+    }
+    /**
+     * Binds the realtime-session factory (the model-session creation seam).
+     *
+     * @param factory The factory that opens an {@link IRealtimeSession} for an agent.
+     */
+    SetSessionFactory(factory) {
+        this.sessionFactory = factory;
+    }
+    /**
+     * Overrides the token service used to mint the bot token (e.g. to inject explicit credentials).
+     *
+     * @param service The token service to use.
+     */
+    SetTokenService(service) {
+        this.tokenService = service;
+    }
+    /**
+     * Overrides the bridge operations used to resolve the provider + start/stop the bridge session (the
+     * injectable {@link AIBridgeEngine} seam — primarily for unit testing).
+     *
+     * @param ops The bridge operations to use.
+     */
+    SetBridgeOps(ops) {
+        this.bridgeOps = ops;
+    }
+    /**
+     * Starts the agent's presence in a LiveKit room: mints the bot token, opens the realtime session, and
+     * bridges it into the room.
+     *
+     * @param params The session parameters.
+     * @returns The active session handles.
+     * @throws {Error} when the LiveKit provider is not configured/registered or the session factory is unbound.
+     */
+    async StartAgentRoomSession(params) {
+        await this.bridgeOps.Config(false, params.ContextUser, params.MetadataProvider);
+        const provider = this.bridgeOps.ProviderByDriverClass(LIVEKIT_BRIDGE_DRIVER_CLASS);
+        if (!provider) {
+            throw new Error(`No active 'MJ: AI Bridge Providers' row with DriverClass='${LIVEKIT_BRIDGE_DRIVER_CLASS}' was found. ` +
+                'Seed/activate the LiveKit provider row before starting a room session.');
+        }
+        const botName = params.AgentName ?? 'Agent';
+        const botIdentity = `agent-${params.AgentSessionID}`;
+        const botToken = await this.tokenService.MintBotToken(params.RoomName, botIdentity, botName);
+        // Multi-agent MEETING detection: if the room already holds an agent, THIS agent joins as a meeting
+        // participant — auto-response OFF, speaks only when addressed by name. The first agent in a room stays
+        // a normal 1:1 voice (it answers freely; it isn't retroactively re-gated). The names the agent answers
+        // to drive both its addressing matcher (the GATE) and the meeting prompt phrasing.
+        const roomKey = params.RoomName.trim().toLowerCase();
+        const selfNames = [botName, ...(params.AgentAliases ?? [])].map(n => n.trim()).filter(n => n.length > 0);
+        const isMeeting = (this.roomRosters.get(roomKey)?.length ?? 0) > 0;
+        const session = await this.sessionFactory({
+            AgentID: params.AgentID,
+            AgentName: params.AgentName,
+            TargetAgentID: params.TargetAgentID,
+            RealtimeModelID: params.RealtimeModelID,
+            RealtimeVoice: params.RealtimeVoice,
+            RoomName: params.RoomName,
+            ContextUser: params.ContextUser,
+            MetadataProvider: params.MetadataProvider,
+            // So the co-agent observability run groups under THIS agent session (parity with native chat).
+            AgentSessionID: params.AgentSessionID,
+            MeetingMode: isMeeting || undefined,
+            SelfNames: isMeeting ? selfNames : undefined,
+        });
+        const active = await this.bridgeOps.StartBridgeSession({
+            AgentSessionID: params.AgentSessionID,
+            AgentID: params.AgentID,
+            Provider: provider,
+            RealtimeSession: session,
+            Address: botToken.ServerUrl,
+            JoinMethod: 'OnDemand',
+            TurnMode: params.TurnMode ?? 'Passive',
+            // Meeting: gate speech to ADDRESSED turns (RegexAddressedMatcher on the agent's names) AND tell the
+            // engine the model's auto-response is off so the bridge becomes the sole trigger. Solo 1:1: respond to
+            // ALL the user's speech (AlwaysAddressedMatcher) with the model's own auto-response — Passive's
+            // name-match would otherwise leave a single agent silent unless you said its name each turn.
+            TurnMatcher: isMeeting ? new RegexAddressedMatcher(selfNames) : new AlwaysAddressedMatcher(),
+            DisableAutoResponse: isMeeting || undefined,
+            // NativeModuleSpecifier tells LiveKitNativeMeetingSdk which native room-client wrapper to load — the
+            // @livekit/rtc-node-backed @memberjunction/ai-bridge-livekit-native by default, overridable via env
+            // (e.g. a one-line module setting Gemini's 16 kHz inbound rate). AccessToken is the pre-signed bot
+            // join token; the room ws URL arrives as `Address`.
+            Configuration: {
+                AccessToken: botToken.Token,
+                BotDisplayName: botName,
+                RoomName: params.RoomName,
+                NativeModuleSpecifier: this.resolveNativeModuleSpecifier(),
+            },
+            ContextUser: params.ContextUser,
+            MetadataProvider: params.MetadataProvider,
+        });
+        this.addToRoster(roomKey, { AgentSessionID: params.AgentSessionID, SessionBridgeID: active.SessionBridgeID, Names: selfNames });
+        LogStatus(`[LiveKitAgentRoomCoordinator] Agent ${botName} bridged into LiveKit room ${params.RoomName} ` +
+            `(bridge ${active.SessionBridgeID}, ${isMeeting ? 'MEETING — addressed-only' : 'solo 1:1'})`);
+        return { SessionBridgeID: active.SessionBridgeID, RoomName: params.RoomName, ServerUrl: botToken.ServerUrl };
+    }
+    /** Appends an agent to a room's roster (creating the room's list on first join). */
+    addToRoster(roomKey, entry) {
+        const roster = this.roomRosters.get(roomKey);
+        if (roster) {
+            roster.push(entry);
+        }
+        else {
+            this.roomRosters.set(roomKey, [entry]);
+        }
+    }
+    /** Removes an agent from whatever room roster holds its bridge id; prunes the room when it empties. */
+    removeFromRoster(sessionBridgeID) {
+        for (const [roomKey, roster] of this.roomRosters) {
+            const next = roster.filter(e => e.SessionBridgeID !== sessionBridgeID);
+            if (next.length === roster.length) {
+                continue;
+            }
+            if (next.length === 0) {
+                this.roomRosters.delete(roomKey);
+            }
+            else {
+                this.roomRosters.set(roomKey, next);
+            }
+            return;
+        }
+    }
+    /** The default native room-client wrapper specifier — the @livekit/rtc-node package this repo ships. */
+    static { this.DEFAULT_NATIVE_MODULE = '@memberjunction/ai-bridge-livekit-native'; }
+    /**
+     * Resolves the native LiveKit room-client module specifier for the bridge session. Prefers the
+     * `LIVEKIT_NATIVE_MODULE` env override (e.g. a deployment's custom-sample-rate wrapper), else the default
+     * {@link DEFAULT_NATIVE_MODULE}. Overridable in tests via {@link SetNativeModuleSpecifier}.
+     */
+    resolveNativeModuleSpecifier() {
+        return (this.nativeModuleSpecifierOverride ??
+            process.env.LIVEKIT_NATIVE_MODULE ??
+            LiveKitAgentRoomCoordinator.DEFAULT_NATIVE_MODULE);
+    }
+    /**
+     * Overrides the native room-client module specifier (primarily for unit testing — production resolves it
+     * from env / the default).
+     *
+     * @param specifier The module specifier to use, or `undefined` to clear the override.
+     */
+    SetNativeModuleSpecifier(specifier) {
+        this.nativeModuleSpecifierOverride = specifier;
+    }
+    /**
+     * Stops an agent room session (the bot leaves the room).
+     *
+     * @param sessionBridgeID The bridge row id returned from {@link StartAgentRoomSession}.
+     * @param reason Why the session is stopping. Default: `'Explicit'`.
+     * @param contextUser The acting user.
+     * @param provider The metadata provider.
+     */
+    async StopAgentRoomSession(sessionBridgeID, reason = 'Explicit', contextUser, provider) {
+        try {
+            return await this.bridgeOps.StopBridgeSession(sessionBridgeID, reason, contextUser, provider);
+        }
+        catch (err) {
+            LogError(`[LiveKitAgentRoomCoordinator] StopAgentRoomSession failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+        finally {
+            // Drop this agent from its room roster so the count reflects who's actually present (the NEXT agent's
+            // meeting-vs-solo decision reads it). Done in finally — even a failed stop means we asked it to leave.
+            this.removeFromRoster(sessionBridgeID);
+        }
+    }
+}
+//# sourceMappingURL=livekit-agent-room-coordinator.js.map

package/dist/livekit-agent-room-coordinator.js.map

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

package/dist/livekit-egress-service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview {@link LiveKitEgressService} — starts/stops room recording (composite egress) via the
+ * LiveKit `EgressClient` (`livekit-server-sdk`). Recording is a server-authorized action, so it lives in
+ * the server package and is invoked through the GraphQL surface — never directly from the browser.
+ *
+ * Egress output storage (S3 / GCS / Azure / LiveKit Cloud bucket) is a deployment concern configured on
+ * the LiveKit project; this service starts a composite MP4 egress with a filepath template and returns the
+ * egress id so the caller can stop it later.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { EgressClient } from 'livekit-server-sdk';
+import { type LiveKitServerConfig } from './livekit-token-service.js';
+/** Parameters for starting a room recording. */
+export interface StartRecordingParams {
+    /** The room to record. */
+    RoomName: string;
+    /** The composite layout (e.g. `'speaker'`, `'grid'`). Default: `'speaker-dark'`. */
+    Layout?: string;
+    /** The output filepath template (provider-specific). Default: `<room>/<timestamp>.mp4`. */
+    Filepath?: string;
+}
+/** The subset of {@link EgressClient} the service drives — an injectable seam for unit testing. */
+export type EgressClientLike = Pick<EgressClient, 'startRoomCompositeEgress' | 'stopEgress' | 'listEgress'>;
+/** Converts a `ws(s)://` server URL to its `http(s)://` form for the egress client. */
+export declare function wsToHttpUrl(url: string): string;
+/** A normalized recording (egress) status. */
+export interface RecordingInfo {
+    /** The egress id (pass to {@link LiveKitEgressService.StopRecording}). */
+    EgressID: string;
+    /** The room being recorded. */
+    RoomName: string;
+    /** The raw egress status string. */
+    Status: string;
+}
+/** Starts/stops/lists LiveKit room recordings (composite egress). */
+export declare class LiveKitEgressService {
+    private readonly client;
+    /**
+     * @param config Explicit credentials; omitted fields fall back to environment variables (via
+     *   {@link LiveKitTokenService}). The egress client uses the HTTP(S) form of the server URL.
+     * @param client An injectable egress client (primarily for unit testing); defaults to a real
+     *   `EgressClient` built from the resolved credentials.
+     */
+    constructor(config?: Partial<LiveKitServerConfig>, client?: EgressClientLike);
+    /**
+     * Starts a composite recording of a room.
+     *
+     * @param params The recording parameters.
+     * @returns The started recording info.
+     */
+    StartRoomRecording(params: StartRecordingParams): Promise<RecordingInfo>;
+    /**
+     * Stops a recording.
+     *
+     * @param egressId The egress id returned by {@link StartRoomRecording}.
+     * @returns The final recording info.
+     */
+    StopRecording(egressId: string): Promise<RecordingInfo>;
+    /**
+     * Lists active recordings for a room.
+     *
+     * @param roomName The room to query.
+     * @returns The active recordings.
+     */
+    ListActiveRecordings(roomName: string): Promise<RecordingInfo[]>;
+    /** Maps an SDK `EgressInfo` to the normalized {@link RecordingInfo}. */
+    private toRecordingInfo;
+}
+//# sourceMappingURL=livekit-egress-service.d.ts.map

package/dist/livekit-egress-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit-egress-service.d.ts","sourceRoot":"","sources":["../src/livekit-egress-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAuD,MAAM,oBAAoB,CAAC;AACvG,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAExF,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,EAAE,0BAA0B,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC;AAE5G,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C;;;;;OAKG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC,EAAE,gBAAgB;IAM5E;;;;;OAKG;IACU,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAOrF;;;;;OAKG;IACU,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAKpE;;;;;OAKG;IACU,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAK7E,wEAAwE;IACxE,OAAO,CAAC,eAAe;CAGxB"}

package/dist/livekit-egress-service.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview {@link LiveKitEgressService} — starts/stops room recording (composite egress) via the
+ * LiveKit `EgressClient` (`livekit-server-sdk`). Recording is a server-authorized action, so it lives in
+ * the server package and is invoked through the GraphQL surface — never directly from the browser.
+ *
+ * Egress output storage (S3 / GCS / Azure / LiveKit Cloud bucket) is a deployment concern configured on
+ * the LiveKit project; this service starts a composite MP4 egress with a filepath template and returns the
+ * egress id so the caller can stop it later.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { EgressClient, EncodedFileOutput, EncodedFileType } from 'livekit-server-sdk';
+import { LiveKitTokenService } from './livekit-token-service.js';
+/** Converts a `ws(s)://` server URL to its `http(s)://` form for the egress client. */
+export function wsToHttpUrl(url) {
+    return url.replace(/^ws/i, 'http');
+}
+/** Starts/stops/lists LiveKit room recordings (composite egress). */
+export class LiveKitEgressService {
+    /**
+     * @param config Explicit credentials; omitted fields fall back to environment variables (via
+     *   {@link LiveKitTokenService}). The egress client uses the HTTP(S) form of the server URL.
+     * @param client An injectable egress client (primarily for unit testing); defaults to a real
+     *   `EgressClient` built from the resolved credentials.
+     */
+    constructor(config, client) {
+        const token = new LiveKitTokenService(config);
+        const httpUrl = wsToHttpUrl(token.ServerUrl);
+        this.client = client ?? new EgressClient(httpUrl, config?.ApiKey ?? process.env.LIVEKIT_API_KEY, config?.ApiSecret ?? process.env.LIVEKIT_API_SECRET);
+    }
+    /**
+     * Starts a composite recording of a room.
+     *
+     * @param params The recording parameters.
+     * @returns The started recording info.
+     */
+    async StartRoomRecording(params) {
+        const filepath = params.Filepath ?? `${params.RoomName}/${Date.now()}.mp4`;
+        const output = new EncodedFileOutput({ fileType: EncodedFileType.MP4, filepath });
+        const info = await this.client.startRoomCompositeEgress(params.RoomName, { file: output }, { layout: params.Layout ?? 'speaker-dark' });
+        return this.toRecordingInfo(info, params.RoomName);
+    }
+    /**
+     * Stops a recording.
+     *
+     * @param egressId The egress id returned by {@link StartRoomRecording}.
+     * @returns The final recording info.
+     */
+    async StopRecording(egressId) {
+        const info = await this.client.stopEgress(egressId);
+        return this.toRecordingInfo(info, info.roomName);
+    }
+    /**
+     * Lists active recordings for a room.
+     *
+     * @param roomName The room to query.
+     * @returns The active recordings.
+     */
+    async ListActiveRecordings(roomName) {
+        const list = await this.client.listEgress({ roomName, active: true });
+        return list.map((info) => this.toRecordingInfo(info, roomName));
+    }
+    /** Maps an SDK `EgressInfo` to the normalized {@link RecordingInfo}. */
+    toRecordingInfo(info, roomName) {
+        return { EgressID: info.egressId, RoomName: info.roomName || roomName, Status: String(info.status ?? 'unknown') };
+    }
+}
+//# sourceMappingURL=livekit-egress-service.js.map

package/dist/livekit-egress-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit-egress-service.js","sourceRoot":"","sources":["../src/livekit-egress-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAmB,MAAM,oBAAoB,CAAC;AACvG,OAAO,EAAE,mBAAmB,EAA4B,MAAM,yBAAyB,CAAC;AAexF,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,CAAC;AAYD,qEAAqE;AACrE,MAAM,OAAO,oBAAoB;IAG/B;;;;;OAKG;IACH,YAAY,MAAqC,EAAE,MAAyB;QAC1E,MAAM,KAAK,GAAG,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,IAAI,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACxJ,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,kBAAkB,CAAC,MAA4B;QAC1D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,GAAG,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC;QAC3E,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,wBAAwB,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,cAAc,EAAE,CAAC,CAAC;QACxI,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,aAAa,CAAC,QAAgB;QACzC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,oBAAoB,CAAC,QAAgB;QAChD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,wEAAwE;IAChE,eAAe,CAAC,IAAgB,EAAE,QAAgB;QACxD,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,SAAS,CAAC,EAAE,CAAC;IACpH,CAAC;CACF"}

package/dist/livekit-token-service.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview {@link LiveKitTokenService} — mints scoped LiveKit access tokens (JWTs) server-side via
+ * `livekit-server-sdk`. This is the missing browser-facing seam: the bridge already joins the *agent bot*
+ * with an MJ-minted token, but a *human* participant needs their own scoped token for the same room. The
+ * service mints both, encoding room + grants + role metadata, and never exposes the API secret to clients.
+ *
+ * Credentials resolve from explicit config or the standard `LIVEKIT_URL` / `LIVEKIT_API_KEY` /
+ * `LIVEKIT_API_SECRET` environment variables (the MJ deployment supplies them; never inline secrets).
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+/** Resolved LiveKit server credentials + URL. */
+export interface LiveKitServerConfig {
+    /** The LiveKit server URL clients connect to (e.g. `wss://livekit.myorg.com`). */
+    ServerUrl: string;
+    /** The LiveKit API key. */
+    ApiKey: string;
+    /** The LiveKit API secret (server-only — never sent to clients). */
+    ApiSecret: string;
+}
+/** The role a minted token grants, stamped into participant metadata for UI role resolution. */
+export type LiveKitTokenRole = 'host' | 'agent' | 'participant';
+/** Parameters for minting a single access token. */
+export interface MintTokenParams {
+    /** The room name the token authorizes joining. */
+    RoomName: string;
+    /** The participant identity to embed (stable, application-assigned). */
+    Identity: string;
+    /** The display name to publish. */
+    DisplayName?: string;
+    /** The role stamped into participant metadata (drives the UI's agent/host badges). */
+    Role?: LiveKitTokenRole;
+    /** Whether the participant may publish media. Default: true. */
+    CanPublish?: boolean;
+    /** Whether the participant may subscribe to others. Default: true. */
+    CanSubscribe?: boolean;
+    /** Whether the participant may publish data-channel messages. Default: true. */
+    CanPublishData?: boolean;
+    /** Token lifetime in seconds. Default: 3600 (1 hour). */
+    TtlSeconds?: number;
+    /** Extra metadata merged into the participant metadata JSON. */
+    Metadata?: Record<string, unknown>;
+}
+/** A minted token plus the connection coordinates a client needs to join. */
+export interface MintedToken {
+    /** The LiveKit server URL to connect to. */
+    ServerUrl: string;
+    /** The signed JWT access token. */
+    Token: string;
+    /** The participant identity embedded in the token. */
+    Identity: string;
+    /** The room name the token authorizes. */
+    RoomName: string;
+}
+/** Mints scoped LiveKit access tokens. Stateless apart from its resolved credentials. */
+export declare class LiveKitTokenService {
+    private readonly config;
+    /**
+     * @param config Explicit credentials; any omitted field falls back to the corresponding environment
+     *   variable (`LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`).
+     */
+    constructor(config?: Partial<LiveKitServerConfig>);
+    /** Whether the service has the credentials needed to mint tokens. */
+    get IsConfigured(): boolean;
+    /** The configured server URL (for callers that need to return it to clients). */
+    get ServerUrl(): string;
+    /**
+     * Mints an access token for the given parameters.
+     *
+     * @param params The token parameters (room, identity, grants, role).
+     * @returns The minted token + connection coordinates.
+     * @throws {Error} when credentials are not configured.
+     */
+    MintToken(params: MintTokenParams): Promise<MintedToken>;
+    /**
+     * Mints a token for a HUMAN participant (publish + subscribe + data, `participant` role).
+     *
+     * @param roomName The room to join.
+     * @param identity The participant identity.
+     * @param displayName The display name.
+     * @param ttlSeconds Optional token lifetime.
+     */
+    MintClientToken(roomName: string, identity: string, displayName?: string, ttlSeconds?: number): Promise<MintedToken>;
+    /**
+     * Mints a token for the AGENT bot (publish + subscribe + data, `agent` role metadata so the UI badges
+     * it correctly). The bridge passes this in its session `Configuration.AccessToken`.
+     *
+     * @param roomName The room to join.
+     * @param identity The bot identity.
+     * @param displayName The bot display name.
+     */
+    MintBotToken(roomName: string, identity: string, displayName?: string): Promise<MintedToken>;
+    /** Builds the LiveKit video grant from the params (defaults: publish + subscribe + data all on). */
+    private buildGrant;
+    /** Builds the participant metadata JSON string, always stamping the role for UI resolution. */
+    private buildMetadata;
+    /** Throws a clear error when credentials are missing. */
+    private assertConfigured;
+}
+//# sourceMappingURL=livekit-token-service.d.ts.map

package/dist/livekit-token-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"livekit-token-service.d.ts","sourceRoot":"","sources":["../src/livekit-token-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAEhE,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yFAAyF;AACzF,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAE7C;;;OAGG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IAQjD,qEAAqE;IACrE,IAAW,YAAY,IAAI,OAAO,CAEjC;IAED,iFAAiF;IACjF,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;;;;;OAMG;IACU,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IAarE;;;;;;;OAOG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI3H;;;;;;;OAOG;IACI,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAInG,oGAAoG;IACpG,OAAO,CAAC,UAAU;IAUlB,+FAA+F;IAC/F,OAAO,CAAC,aAAa;IAIrB,yDAAyD;IACzD,OAAO,CAAC,gBAAgB;CAQzB"}

package/dist/livekit-token-service.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview {@link LiveKitTokenService} — mints scoped LiveKit access tokens (JWTs) server-side via
+ * `livekit-server-sdk`. This is the missing browser-facing seam: the bridge already joins the *agent bot*
+ * with an MJ-minted token, but a *human* participant needs their own scoped token for the same room. The
+ * service mints both, encoding room + grants + role metadata, and never exposes the API secret to clients.
+ *
+ * Credentials resolve from explicit config or the standard `LIVEKIT_URL` / `LIVEKIT_API_KEY` /
+ * `LIVEKIT_API_SECRET` environment variables (the MJ deployment supplies them; never inline secrets).
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { AccessToken } from 'livekit-server-sdk';
+/** Mints scoped LiveKit access tokens. Stateless apart from its resolved credentials. */
+export class LiveKitTokenService {
+    /**
+     * @param config Explicit credentials; any omitted field falls back to the corresponding environment
+     *   variable (`LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`).
+     */
+    constructor(config) {
+        this.config = {
+            ServerUrl: config?.ServerUrl ?? process.env.LIVEKIT_URL ?? '',
+            ApiKey: config?.ApiKey ?? process.env.LIVEKIT_API_KEY ?? '',
+            ApiSecret: config?.ApiSecret ?? process.env.LIVEKIT_API_SECRET ?? '',
+        };
+    }
+    /** Whether the service has the credentials needed to mint tokens. */
+    get IsConfigured() {
+        return Boolean(this.config.ServerUrl && this.config.ApiKey && this.config.ApiSecret);
+    }
+    /** The configured server URL (for callers that need to return it to clients). */
+    get ServerUrl() {
+        return this.config.ServerUrl;
+    }
+    /**
+     * Mints an access token for the given parameters.
+     *
+     * @param params The token parameters (room, identity, grants, role).
+     * @returns The minted token + connection coordinates.
+     * @throws {Error} when credentials are not configured.
+     */
+    async MintToken(params) {
+        this.assertConfigured();
+        const at = new AccessToken(this.config.ApiKey, this.config.ApiSecret, {
+            identity: params.Identity,
+            name: params.DisplayName,
+            ttl: params.TtlSeconds ?? 3600,
+            metadata: this.buildMetadata(params),
+        });
+        at.addGrant(this.buildGrant(params));
+        const token = await at.toJwt();
+        return { ServerUrl: this.config.ServerUrl, Token: token, Identity: params.Identity, RoomName: params.RoomName };
+    }
+    /**
+     * Mints a token for a HUMAN participant (publish + subscribe + data, `participant` role).
+     *
+     * @param roomName The room to join.
+     * @param identity The participant identity.
+     * @param displayName The display name.
+     * @param ttlSeconds Optional token lifetime.
+     */
+    MintClientToken(roomName, identity, displayName, ttlSeconds) {
+        return this.MintToken({ RoomName: roomName, Identity: identity, DisplayName: displayName, Role: 'participant', TtlSeconds: ttlSeconds });
+    }
+    /**
+     * Mints a token for the AGENT bot (publish + subscribe + data, `agent` role metadata so the UI badges
+     * it correctly). The bridge passes this in its session `Configuration.AccessToken`.
+     *
+     * @param roomName The room to join.
+     * @param identity The bot identity.
+     * @param displayName The bot display name.
+     */
+    MintBotToken(roomName, identity, displayName) {
+        return this.MintToken({ RoomName: roomName, Identity: identity, DisplayName: displayName, Role: 'agent' });
+    }
+    /** Builds the LiveKit video grant from the params (defaults: publish + subscribe + data all on). */
+    buildGrant(params) {
+        return {
+            roomJoin: true,
+            room: params.RoomName,
+            canPublish: params.CanPublish ?? true,
+            canSubscribe: params.CanSubscribe ?? true,
+            canPublishData: params.CanPublishData ?? true,
+        };
+    }
+    /** Builds the participant metadata JSON string, always stamping the role for UI resolution. */
+    buildMetadata(params) {
+        return JSON.stringify({ mjRole: params.Role ?? 'participant', ...(params.Metadata ?? {}) });
+    }
+    /** Throws a clear error when credentials are missing. */
+    assertConfigured() {
+        if (!this.IsConfigured) {
+            throw new Error('LiveKitTokenService is not configured. Set LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET ' +
+                '(or pass them to the constructor) before minting tokens.');
+        }
+    }
+}
+//# sourceMappingURL=livekit-token-service.js.map

package/dist/livekit-token-service.js.map

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

package/package.json

@@ -1,10 +1,37 @@
 {
   "name": "@memberjunction/livekit-room-server",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/livekit-room-server",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.42.0",
+  "description": "MemberJunction: Server-side LiveKit room support — mints scoped client/bot access tokens (livekit-server-sdk) and provides the session-start coordinator that opens a realtime model session and bridges it into a LiveKit room via AIBridgeEngine. The MJ realtime-bridge ↔ LiveKit UI seam.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/core": "5.42.0",
+    "@memberjunction/global": "5.42.0",
+    "@memberjunction/core-entities": "5.42.0",
+    "@memberjunction/ai": "5.42.0",
+    "@memberjunction/ai-bridge-base": "5.42.0",
+    "@memberjunction/ai-bridge-server": "5.42.0",
+    "@memberjunction/ai-bridge-livekit": "5.42.0",
+    "livekit-server-sdk": "^2.9.7"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.11",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }